> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Authentication

Every CAIL Health API request is authenticated with a bearer token. The API has two audiences, and each authenticates on its own path with its own identity provider. The two paths never mix: a token issued for one audience is rejected by the other audience's endpoints.

For the reasoning behind this split, see [Auth model](/concepts/auth-model).

## Member clients (Firebase Auth)

Patient and member applications sign in anonymously through Firebase Auth and call the API with the resulting ID token.

* Sign-in is anonymous. No name, email, or other identifier is required or carried.
* Endpoints that accept this path are marked with the `firebaseBearer` scheme.

To call a member endpoint:

1. Use the Firebase SDK to obtain an anonymous ID token.
2. Send the token on every request in the `Authorization` header.
3. The API validates the token and resolves the active jurisdiction for the request.

## Operator clients (Auth0)

Operator and commissioner applications sign in through Auth0 and call the API with the resulting ID token.

* The token identifies the user and the organization the user belongs to.
* The organization governs what the user can see and do.
* Endpoints that accept this path are marked with the `auth0Bearer` scheme.

To call an operator endpoint:

1. Sign the user in through your application's Auth0 login.
2. Send the resulting token on every request in the `Authorization` header.
3. The API validates the token, derives the organization, and enforces the user's permissions within it.

## Sending the token

Both paths use the same header. Send the token as a bearer credential:

```
Authorization: Bearer <token>
```

Tokens are JSON Web Tokens. Treat them as short-lived: obtain a fresh token from the SDK rather than caching one indefinitely.

## Reading the required scheme

Every operation in this reference declares the scheme it accepts. An operation marked `firebaseBearer` accepts only member tokens; an operation marked `auth0Bearer` accepts only operator tokens. Sending the wrong token type, or no token, fails authentication.

## When authentication fails

* A missing, malformed, or expired token returns `401 Unauthorized`. Obtain a fresh token and retry.
* A valid token whose audience or permissions do not allow the action returns `403 Forbidden`. Retrying with the same token will not succeed.

Both responses use the standard error envelope. See [Errors](/api-reference/errors).