Authentication

Obtain a Bearer token via OAuth2 client credentials, then send it on every request.

The API uses Bearer token authentication, issued via the OAuth2 client credentials flow.

Working example

The backend-auth-flow-demo repository on GitHub is a runnable Node.js backend that gets a token and calls the API.

Getting access

XUND provides your Client Id and API key during onboarding.

Getting a token

Exchange your Client Id and API key for a token:

POST https://login.xund.solutions/api/token

Parameter	Type	Description
`grant_type`	constant `client_credentials`	The requested grant type.
`clientId`	string	The Client Id that belongs to the API key.
`clientSecret`	string	The API key (raw).

{
  "grant_type": "client_credentials",
  "clientId": "***",
  "clientSecret": "***"
}

The response contains the access token:

{
  "access_token": "eyJhbGciOiJI...",
  "token_type": "Bearer"
}

Using the token

Send it as the authorization header on every request:

authorization: Bearer eyJhbGciOiJI...

Tokens expire — request a new one via the same endpoint when yours does; there's no refresh-token flow for this grant type.

The token response carries no expires_in field. The lifetime is configured per environment, so don't hardcode an assumption about it. To know when a token expires, decode the JWT — it carries the standard exp claim (Unix timestamp) — and request a new token shortly before that time. If you'd rather not decode tokens, treat any 401 response as the refresh signal: get a fresh token and retry the request once.

Where your credentials live

The API key and the Bearer token are confidential credentials — keep them server-side, always. Never ship either one to a browser or mobile client: anyone who extracts them can run checks and read check data on your account. For a patient-facing web or mobile app, put a thin backend proxy between your UI and the XUND API — the browser talks to your backend, and only your backend holds the credentials, exchanges the token, and calls XUND. The API is designed for server-to-server calls, so don't plan on calling it directly from browser JavaScript.

Example: calling an endpoint

Here the token is used against GET /v1/imprintResources, which needs only the token and a language header:

GET https://medical.api.xund.solutions/v1/imprintResources
authorization: Bearer eyJhbGciOiJI...
language: en

A successful call returns 200 with JSON:

{
  "id": "3f1a7c2e-9b4d-4e2a-8c1f-6a2d5e9b7c3a",
  "language": "en",
  "medicalProductInfo": { ... },
  "impressum": { ... }
}

The API reference lists every field.

A 401 here (API_KEY_OR_TOKEN_MISSING, INVALID_TOKEN, or similar) almost always means the authorization header is missing, malformed, or the token expired — get a fresh one from the token endpoint above.