Olira uses two authentication mechanisms depending on the actor making the request.
| Actor | Method | Notes |
|---|
| Organization admin | API Key | Scoped per organization, created in the Olira Console |
| Patient / client device | Patient Token | Short-lived JWT minted by your backend, scoped to one patient |
API keys
API keys are created in the Olira Console and scoped to your organization. Each key can be assigned specific scopes to limit access to only the endpoints your integration requires.
Send your API key as a Bearer token in the Authorization header on every request:
Authorization: Bearer YOUR_OLIRA_API_KEY
Scopes
Each API key carries one or more scopes that limit what it can do. Assign only the scopes your integration needs.
| Scope | Description |
|---|
sdk:event-log | Log health events via log(), log_batch(), and log_fhir() |
api:manage-patients | Create, read, update, and deactivate patients; manage cohorts |
api:org-config | Read and update organization platform configuration |
sdk:patient-token | Mint patient-scoped JWTs via get_patient_token() |
sdk:state-read | Read patient state (stable data, event modules, summaries, event logs, events, memories) |
sdk:historical-ingest | Create and manage bulk historical data ingestion jobs (SDK, CLI, or REST) |
mcp:patient-state | Query patient state via the MCP Patient State server |
Patient tokens
A Patient Token is a short-lived JWT (15 minutes) scoped to a single patient. Use it when a patient device or client-side app needs to call Olira directly (for example, when connecting to the MCP Patient State server from a mobile app).
Patients are never issued API keys. Instead, your backend mints a token on their behalf and forwards it. The token is locked to the patient server-side (the recipient cannot access any other patient’s data).
# Your backend (requires sdk:patient-token scope on your API key):
client = OliraClient(api_key="YOUR_API_KEY")
token = client.get_patient_token(patient_id="8a4fde23-...")
# Forward token.access_token to the patient device
# The device authenticates as:
# Authorization: Bearer <token.access_token>
Patient Tokens expire after 15 minutes. Your backend should mint a fresh
token on each session (do not cache them long-term).
