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

# Authentication

> Organization API keys, personal API keys, partner apps (M2M) and MCP OAuth: how each one signs in and what each one sees.

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

```http theme={null}
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](#organization-api-keys) | The clinic | Every center, limited to the key's permissions |
| A script for yourself | [Personal API key](#personal-api-keys) | You | Only what you see in Brelio, limited to the key's permissions |
| Software you sell to many clinics | [Partner app](#partner-apps-m2m) | The clinic that created it | Every center, limited to the app's permissions |
| An AI assistant (Claude, ChatGPT, Cursor…) | [MCP OAuth](#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](https://docs.brelio.com/en/concepts/data-areas.md) 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.

**1. 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.

**2. 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.

**3. Call the API**

```bash theme={null}
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](https://docs.brelio.com/en/concepts/data-areas.md#patient-data-consent)).

**Revoke** a key in the same screen. A key can also revoke itself, for example when a tool detects it leaked:

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

> [!WARNING]
>
> **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](https://docs.brelio.com/en/changelog.md#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.

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

```json Response (shape) theme={null}
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 3600 }
```

```bash theme={null}
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](https://docs.brelio.com/en/quickstart/mcp.md).

For client developers, the server follows the MCP authorization spec:

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

```bash theme={null}
curl https://api.brelio.app/.well-known/oauth-protected-resource/mcp
```

```json Response theme={null}
{
  "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**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.