Authentication

Every request to the MCP server requires a Bearer token in the Authorization header. There are four supported token types, evaluated in this priority order:

Priority	Token format	Who uses it	How to obtain
1	Opaque Olira API key (`YOUR_API_KEY`)	Backend services, Cursor, CI pipelines	Console → Settings → API Keys, or `olira keys create`
2	Olira-issued RS256 JWT (`iss: "olira-api-keys"`)	SDK / automated clients	`POST /auth/token`: exchange your API key for a short-lived JWT
3	Patient Token (RS256, `user_type: "patient"`)	Patient-facing apps and agents	`get_patient_token` / `GetPatientToken` via the SDK
4	Auth0 JWT (interactive console session)	Provider agents with a console login	Auth0 Authorization Code + PKCE via `olira login`

Required scope

All API keys used with the MCP must carry the mcp:patient-state scope. Keys without this scope receive 403 Forbidden. Create a key with the correct scope in the Console or with the CLI:

olira keys create --name "my-agent" --scopes mcp:patient-state

Patient Tokens

Patient Tokens are short-lived (15 min) JWTs locked to a single patient. Use them when running an agent on a patient-facing device; the patient_id is embedded in the token and cannot be overridden by the caller. Mint server-side using the SDK. The API key used here must carry the sdk:patient-token scope; create one with olira keys create --name "token-minter" --scopes sdk:patient-token.

import olira

olira.init(api_key="YOUR_API_KEY")
token = olira.get_patient_token(patient_id="<patient-id>")
# pass token.access_token to your client

using Olira;

OliraModule.Init(apiKey: "YOUR_API_KEY");
var token = OliraModule.GetPatientToken(patientId: "<patient-id>");
// pass token.AccessToken to your client

When using a Patient Token, omit patient_id from all tool arguments; it is resolved automatically from the token.

Authentication errors

Status	Meaning
`401`	Missing, expired, or malformed token
`403`	Valid token but missing `mcp:patient-state` scope, or patient not in your organization

Getting started

Tools

Advanced

Authentication

Required scope

Patient Tokens

Authentication errors

​Required scope

​Patient Tokens

​Authentication errors

Required scope

Patient Tokens

Authentication errors