Introduction

Authentication

The two token paths and how to send a token
View as MarkdownOpen in Claude

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.

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.