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.
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
| Environment | Token URL | Scope |
|---|---|---|
| Production | https://arzamed-domain.auth.eu-west-1.amazoncognito.com/oauth2/token | https://api.platform.arzamed.com/readhttps://api.platform.arzamed.com/write |
| Sandbox | https://arzamed-domain-uat.auth.eu-west-1.amazoncognito.com/oauth2/token | https://api-uat.nextgen.arzamed.com/readhttps://api-uat.nextgen.arzamed.com/write |
Request parameters
| Parameter | Value |
|---|---|
grant_type required | client_credentials |
scope required | https://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
{
"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:
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.
| Scope | Grants access to |
|---|---|
https://api.platform.arzamed.com/read | All GET endpoints for the issuing equipe: practitioners, their calendars, patients, treatments, locations and free slots. |
https://api.platform.arzamed.com/write | The 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:
- Gateway — validates the token signature, checks that it has not expired, and verifies it was issued for the external API.
- Application layer — additionally verifies that the
client_idin 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
| Status | Cause |
|---|---|
401 | No Authorization header, or the token is malformed or expired. |
403 | Token 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). |