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 equipe. Each equipe's administrator generates their own API key from the ArzaMed client app. Your client_id and client_secret are shown when the key is created. The token URL is the same for every key and is listed below.

Requesting a token

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

POST https://arzamed-domain.auth.eu-west-1.amazoncognito.com/oauth2/token
cURL
curl -X POST "https://arzamed-domain.auth.eu-west-1.amazoncognito.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=https://api.platform.arzamed.com/read%20https://api.platform.arzamed.com/write"

Token URL and scope by environment

EnvironmentToken URLScope
Productionhttps://arzamed-domain.auth.eu-west-1.amazoncognito.com/oauth2/tokenhttps://api.platform.arzamed.com/read
https://api.platform.arzamed.com/write
Sandboxhttps://arzamed-domain-uat.auth.eu-west-1.amazoncognito.com/oauth2/tokenhttps://api-uat.nextgen.arzamed.com/read
https://api-uat.nextgen.arzamed.com/write

Request parameters

ParameterValue
grant_type requiredclient_credentials
scope requiredhttps://api.platform.arzamed.com/read https://api.platform.arzamed.com/write

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
}
FieldDescription
access_tokenThe bearer token to attach to API requests. It is a signed RS256 JWT.
token_typeAlways Bearer.
expires_inLifetime 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 token endpoint is rate-limited per IP address. An integration that requests a new token for every call can be temporarily blocked with 403, so always cache the token.

The API is for server-to-server use only. It does not allow cross-origin (CORS) requests, so it can't be called from a web browser, and the client secret must never be sent to one.

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 has two scopes. Request the ones you need explicitly in the token call, separated by a space. A request without the scope it needs is refused with 403.

ScopeGrants access to
https://api.platform.arzamed.com/readAll GET endpoints for the issuing equipe: practitioners, their calendars, patients, treatments, locations and free slots.
https://api.platform.arzamed.com/writeThe endpoints that create or change data (POST, PATCH): adding patients, and booking, changing or cancelling visits.

Token validation

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

  1. Gateway — validates the token signature, checks that it has not expired, and verifies it was issued for the external API.
  2. 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 token signature is technically still valid.

Error responses

StatusCause
401No Authorization header, or the token is malformed or expired.
403Token is valid but the API key has been revoked, disabled, or has expired (a key is valid for one year from when it's generated; on a paid plan it stays valid until the plan's renewal date plus 30 days), the token was issued for a different environment, or it lacks the scope the request needs (read for GET, write for POST and PATCH).