Authentication and Credentials
Create OAuth credentials for a workspace in the Clinia Console, exchange them for an access token, and rotate or delete them.
A credential is an OAuth client ID and secret that belongs to one workspace. A workspace can hold several credentials. Your application exchanges the ID and secret for a bearer token through the OAuth 2.0 client credentials flow, then sends that token with every API request. The audit trail records the credential as the caller of each request, along with the person who created it, so give each application its own credential.
Owners and admins can create and delete credentials. Every member can see the list of credentials for a workspace. See Team and roles to understand what each role can do.
Access levels
Every credential has an access level, which sets the OAuth scope its tokens carry.
- Read grants the
readscope. The application can read patient data but cannot create, change or delete anything. - Read & Write grants the
writescope, which includesread. The application can also ingest data and create and delete patients.
The access level is fixed when you create the credential. Use Read for agents that only consult patient context, and Read & Write for ingestion workers that push records into the Context Engine.
Create a credential
The Console shows the client secret only once. If you lose it, create a new credential and delete the old one.
You cannot add a credential to a disabled workspace.
Get an access token
Exchange the client ID and secret for a token with the OAuth 2.0 client credentials grant:
curl -X POST "https://console.clinia.cloud/api/auth/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=<client-id>&client_secret=<client-secret>&resource=https://console.clinia.cloud"{
"access_token": "<access-token>",
"expires_in": 3600,
"expires_at": 1767229200,
"token_type": "Bearer",
"scope": "read write"
}The resource parameter is required. Without it, the token endpoint returns a token that the Context Engine will reject.
Send the token as Authorization: Bearer <access-token> on every request to your workspace URL. Tokens expire after one hour, and there is no refresh token, so cache the token and request a new one shortly before expires_at.
Rotate or delete a credential
To rotate a credential, create a new one, switch your application to it, then delete the old one.
To delete a credential, select the delete icon on its row in the OAuth credentials section. Deletion takes effect immediately, so the deleted credential can no longer get new tokens. A token it already received keeps working until it expires, which takes at most one hour.
When a call returns 403 insufficient_scope
A 403 response with the header WWW-Authenticate: Bearer error="insufficient_scope" means the token carries only the read scope and the operation requires write. Create a credential with Read & Write for that application, because an existing credential's access level cannot change. Each operation's page in the API reference gives the scope it requires.