Authentication

Every request to the Arzamed API requires a valid OAuth2 bearer token in the Authorization header.

The Arzamed API uses the OAuth2 client credentials grant — a server-to-server flow designed for backend integrations where there is no end user involved. You exchange your client_id and client_secret for a short-lived access token, then use that token on every API call.

ℹ️

Credentials are issued per clinic. Each clinic's administrator generates their own API key from the Arzamed client app. Your client_id, client_secret, and token_url are all provided together when the key is created.

Requesting a token

Send a POST request to your token URL. Pass your credentials as HTTP Basic Auth and the grant parameters as a form-encoded body.

POST YOUR_TOKEN_URL

cURL

curl -X POST "YOUR_TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=https://api.nextgen.arzamed.com/read"

Request parameters

Parameter	Value
`grant_type` required	`client_credentials`
`scope` required	`https://api.nextgen.arzamed.com/read`

Credentials are passed via HTTP Basic Authentication (the -u flag in cURL): client_id as the username and client_secret as the password.

Token response

JSON · 200 OK

{
  "access_token": "eyJraWQiOiJrZXktaWQiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Description
`access_token`	The bearer token to attach to API requests. It is a signed RS256 JWT.
`token_type`	Always `Bearer`.
`expires_in`	Lifetime in seconds. Tokens expire after 3600 seconds (1 hour).

Using the token

Include the token in the Authorization header on every API request:

HTTP

Authorization: Bearer eyJraWQiOiJrZXktaWQiLCJhbGciOiJSUzI1NiJ9...

Token caching

Tokens expire after one hour. Re-requesting a token on every API call is wasteful and will slow down your integration. Cache the token and request a new one only when it is close to expiry.

A simple strategy: store the token together with Date.now() + (expires_in - 60) * 1000 as the expiry timestamp, and refresh whenever the current time exceeds that value (the 60-second buffer accounts for clock skew and network latency).

🔒

The client credentials grant does not issue a refresh token. When the access token expires, request a new one using the same client credentials. There is no other renewal mechanism.

Scopes

The Arzamed external API exposes a single scope. Always request it explicitly in the token call.

Scope	Grants access to
`https://api.nextgen.arzamed.com/read`	Read all available endpoints for the issuing clinic (doctors, and upcoming calendar events and patients).

Token validation

Every token is validated at two layers before a request reaches business logic:

API Gateway — validates the JWT signature against Cognito's public keys (JWKS), checks exp, and verifies the issuer is bound to the correct user pool.
Application layer — additionally verifies that the client_id in the token is recognised, active, and has not expired. A 403 is returned if any check fails.

This means a revoked API key is rejected at the application layer even if the JWT signature is technically still valid.

Error responses

Status	Cause
`401`	No `Authorization` header, or the token is malformed or expired.
`403`	Token is valid but the API key has been revoked, the key has passed its expiry date, or the token was issued by a different Cognito user pool.