> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olira.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Token types, required scopes, and Patient Tokens for the Olira MCP Patient State server.

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         | `client.get_patient_token(patient_id)` via the Python 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](/cli/keys):

```bash theme={null}
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 [Python SDK](/reference/sdk) (`pip install olira`).
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`.

```python theme={null}
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
```

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 |