Authentication

Every call carries one credential in the Authorization header. Nobody calls anonymously, and every credential belongs to exactly one clinic (organization).

Authorization: Bearer <credential>

Brelio never issues tokens itself: every credential comes from WorkOS, Brelio’s identity provider, and Brelio checks it on each request.

Choose a credential

You are building	Use	Acts as	Sees
The clinic’s own integration (n8n, Make, an internal script)	Organization API key	The clinic	Every center, limited to the key’s permissions
A script for yourself	Personal API key	You	Only what you see in Brelio, limited to the key’s permissions
Software you sell to many clinics	Partner app	The clinic that created it	Every center, limited to the app’s permissions
An AI assistant (Claude, ChatGPT, Cursor…)	MCP OAuth	You	Exactly what you see in Brelio

Effective access is always an intersection, never a union:

Organization credentials (organization keys, partner apps): the permissions ticked on the key or app, within what the clinic’s plan allows. They never inherit the access of the person who created them.
Personal credentials (personal keys, MCP connections): the credential’s permissions and your current permissions and centers in Brelio, read on every request. If you lose a permission or leave the clinic, every credential acting for you loses it at the same moment.

On top of either, the clinic’s data areas decide which kinds of data any integration may use.

Organization API keys

For the clinic’s own tools. The key does not depend on any person, so it keeps working when staff change.

Create it

In Brelio: Configuración › Integraciones › Claves de API › Nueva clave. Tick only the permissions the tool needs. You cannot give a key a permission you do not hold yourself.

Copy it once

The full key is shown only on creation. Afterwards Brelio lists it by name, its last characters, its permissions and when it was last used.

Call the API

curl https://api.brelio.app/v1/centers \
  -H "Authorization: Bearer $BRELIO_API_KEY"

If the key will read patient data, the owner who creates it also accepts patient-data access for it (see patient-data consent). Revoke a key in the same screen. A key can also revoke itself, for example when a tool detects it leaked:

curl -X POST https://api.brelio.app/v1/api-keys/$KEY_ID/revoke \
  -H "Authorization: Bearer $BRELIO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

A key can never revoke other keys: that takes a person signed in to Brelio (403 CREDENTIAL_SESSION_REQUIRED).

Personal API keys

A personal key acts as you. It is useful for your own scripts and command-line tools: it can never do more than you can in Brelio, and it stops working if you leave the clinic. List your personal keys with GET /v1/me/api-keys, and the assistants you connected with GET /v1/me/connections. Creating or revoking them takes your own session in Brelio: a credential cannot create credentials.

Known limitation (November 2026). Personal keys and MCP connections are refused operations whose permission is granted per center (agenda, free slots, appointments and patients) with 403 OPERATION_FORBIDDEN. Use an organization key for those until this is fixed. See known limitations.

Partner apps (M2M)

For software that serves many clinics. Each clinic creates a partner app for you in Configuración › Integraciones › Apps de partners, ticks its permissions and gives you its client ID and client secret. Your server exchanges them for a short-lived access token with the OAuth 2.0 client_credentials grant, and sends that token as the bearer credential.

curl -X POST https://palatial-engine-44.authkit.app/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id="$BRELIO_CLIENT_ID" \
  -d client_secret="$BRELIO_CLIENT_SECRET"

Response (shape)

{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 3600 }

curl https://api.brelio.app/v1/professionals \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The token carries the clinic (org_id) and the app’s permissions. Brelio refuses a token issued to a person.
Request a new token before expires_in runs out; do not request one per call.
The clinic can see the app in Conexiones and delete it at any time; its tokens then stop working. An app may delete only itself (POST /v1/partner-apps/{id}/revoke).

MCP OAuth

AI assistants connect to https://api.brelio.app/mcp with OAuth 2.1, and you sign in with your Brelio account. You never handle a token. See Connect your AI assistant. For client developers, the server follows the MCP authorization spec:

An unauthenticated call answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.brelio.app/.well-known/oauth-protected-resource/mcp".
That document names the authorization server; Brelio uses WorkOS AuthKit, which supports Client ID Metadata Documents and dynamic client registration.
Request the token with resource=https://api.brelio.app/mcp. The token’s audience must be exactly that address.

curl https://api.brelio.app/.well-known/oauth-protected-resource/mcp

Response

{
  "resource": "https://api.brelio.app/mcp",
  "authorization_servers": ["https://palatial-engine-44.authkit.app"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Brelio",
  "resource_documentation": "https://docs.brelio.com"
}

Access tokens live five minutes and the assistant refreshes them. When you disconnect an assistant in Brelio, its access stops within five minutes.

Keep credentials safe

Store keys and client secrets in a secret manager or environment variables. Never commit them, paste them in a chat, or put them in a URL.
Give each tool its own key with only the permissions it needs, so you can revoke one without touching the others.
Keys are validated with WorkOS and the result is cached for up to 60 seconds, so a revoked key can work for up to a minute.
Every call is recorded with the credential that made it. The clinic sees it in Configuración › Integraciones › Actividad.

Get started

Concepts

Guides

MCP reference

Reference

Authentication

Choose a credential

Organization API keys

Personal API keys

Partner apps (M2M)

MCP OAuth

Keep credentials safe

​Choose a credential

​Organization API keys

​Personal API keys

​Partner apps (M2M)

​MCP OAuth

​Keep credentials safe

Choose a credential

Organization API keys

Personal API keys

Partner apps (M2M)

MCP OAuth

Keep credentials safe