Authentication

HMS4all supports two authentication methods: API keys (recommended for agents) and JWT bearer tokens (for interactive applications).

API Key Authentication (Recommended)

API keys are the recommended way to authenticate MCP clients and A2A agents. Keys are scoped to specific tool categories and rate-limited per key.

Creating an API Key

1. Log in to the admin dashboard
2. Navigate to Automation → API Keys
3. Click “Create API Key”
4. Choose a name, select scopes, and set an expiry date
5. Copy the key immediately — it cannot be viewed again

Using the API Key

Include the key in the Authorization header:

curl https://your-api.hms4all.com/mcp \
  -H "Authorization: Bearer hms4all_sk_abc123def456"

Key Rotation

Rotate keys without downtime: click Rotate on an existing key. This generates a new key and revokes the old one. Update your clients with the new key within the grace period.

Scopes Reference

Each scope controls access to a category of MCP tools. API keys withnull scopes (all scopes) have unrestricted tool access.

JWT Authentication

For interactive applications, use JWT bearer tokens obtained via the login endpoint.

Login

curl -X POST https://your-api.hms4all.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@your-hospital.com",
    "password": "your-password"
  }'

# Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "you@your-hospital.com",
    "role": "ADMIN",
    "tenantId": "tenant-uuid",
    "permissions": ["VIEW_DASHBOARD", "VIEW_OPD", ...]
  }
}

Using the JWT

curl https://your-api.hms4all.com/appointments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
  -H "x-tenant-id: tenant-uuid"

Token Expiry

JWT tokens expire based on the JWT_EXPIRATION server config (default: 24 hours). When a token expires, re-authenticate via the login endpoint.

Rate Limits