> ## 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.

# Autenticación

> Claves de API de la organización, claves personales, apps de partners (M2M) y OAuth de MCP: cómo inicia sesión cada una y qué ve cada una.

Cada llamada lleva una credencial en la cabecera `Authorization`. Nadie llama de forma anónima, y cada credencial pertenece a una sola clínica (organización).

```http theme={null}
Authorization: Bearer <credencial>
```

Brelio nunca emite tokens: todas las credenciales vienen de WorkOS, el proveedor de identidad de Brelio, y Brelio las comprueba en cada petición.

## Elige una credencial

| Estás construyendo | Usa | Actúa como | Ve |
| - | - | - | - |
| Una integración propia de la clínica (n8n, Make, un script interno) | [Clave de API de la organización](#claves-de-api-de-la-organización) | La clínica | Todos los centros, dentro de los permisos de la clave |
| Un script para ti | [Clave personal](#claves-personales) | Tú | Solo lo que ves en Brelio, dentro de los permisos de la clave |
| Software que vendes a muchas clínicas | [App de partner](#apps-de-partners-m2m) | La clínica que la creó | Todos los centros, dentro de los permisos de la app |
| Un asistente de IA (Claude, ChatGPT, Cursor…) | [OAuth de MCP](#oauth-de-mcp) | Tú | Exactamente lo que ves en Brelio |

El acceso efectivo siempre es una **intersección**, nunca una suma:

* **Credenciales de la organización** (claves de la organización, apps de partners): los permisos marcados en la clave o la app, dentro de lo que permite el plan de la clínica. Nunca heredan el acceso de la persona que las creó.
* **Credenciales personales** (claves personales, conexiones MCP): los permisos de la credencial **y** tus permisos y centros actuales en Brelio, leídos en cada petición. Si pierdes un permiso o dejas la clínica, todas las credenciales que actúan por ti lo pierden en ese mismo momento.

Además, en ambos casos, las [áreas de datos](https://docs.brelio.com/es/concepts/data-areas.md) de la clínica deciden qué tipos de datos puede usar cualquier integración.

## Claves de API de la organización

Para las herramientas propias de la clínica. La clave no depende de ninguna persona, así que sigue funcionando aunque cambie el equipo.

**1. Créala**

En Brelio: **Configuración › Integraciones › Claves de API › Nueva clave**. Marca solo los permisos que necesita la herramienta. No puedes dar a una clave un permiso que tú no tienes.

**2. Cópiala una vez**

La clave completa solo se muestra al crearla. Después Brelio la lista por su nombre, sus últimos caracteres, sus permisos y cuándo se usó por última vez.

**3. Llama a la API**

```bash theme={null}
curl https://api.brelio.app/v1/centers \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

Si la clave va a leer datos de pacientes, el propietario que la crea también acepta el acceso a datos de pacientes para ella (consulta el [consentimiento de datos de pacientes](https://docs.brelio.com/es/concepts/data-areas.md#consentimiento-de-datos-de-pacientes)).

**Revoca** una clave en la misma pantalla. Una clave también puede revocarse a sí misma, por ejemplo cuando una herramienta detecta que se ha filtrado:

```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)"
```

Una clave nunca puede revocar otras claves: eso lo hace una persona con sesión en Brelio (`403 CREDENTIAL_SESSION_REQUIRED`).

## Claves personales

Una clave personal actúa como tú. Sirve para tus propios scripts y herramientas de línea de comandos: nunca puede hacer más que tú en Brelio y deja de funcionar si sales de la clínica.

Lista tus claves personales con `GET /v1/me/api-keys`, y los asistentes que has conectado con `GET /v1/me/connections`. Crearlas o revocarlas requiere tu propia sesión en Brelio: una credencial no puede crear credenciales.

> [!WARNING]
>
> **Limitación conocida (noviembre de 2026).** Las claves personales y las conexiones MCP reciben `403 OPERATION_FORBIDDEN` en las operaciones cuyo permiso se concede por centro (agenda, huecos libres, citas y pacientes). Hasta que se corrija, usa una clave de la organización para esas operaciones. Consulta las [limitaciones conocidas](https://docs.brelio.com/es/changelog.md#limitaciones-conocidas).

## Apps de partners (M2M)

Para software que da servicio a muchas clínicas. Cada clínica crea una app de partner para ti en **Configuración › Integraciones › Apps de partners**, marca sus permisos y te da su client ID y su client secret. Tu servidor los cambia por un token de acceso de corta duración con el grant OAuth 2.0 `client_credentials`, y envía ese token como credencial bearer.

```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 Respuesta (forma) 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"
```

* El token lleva la clínica (`org_id`) y los permisos de la app. Brelio rechaza un token emitido a una persona.
* Pide un token nuevo antes de que se acabe `expires_in`; no pidas uno por llamada.
* La clínica ve la app en **Conexiones** y puede eliminarla cuando quiera; sus tokens dejan de funcionar. Una app solo puede eliminarse a sí misma (`POST /v1/partner-apps/{id}/revoke`).

## OAuth de MCP

Los asistentes de IA se conectan a `https://api.brelio.app/mcp` con OAuth 2.1, e inicias sesión con tu cuenta de Brelio. Nunca manejas un token. Consulta [Conecta tu asistente de IA](https://docs.brelio.com/es/quickstart/mcp.md).

Para quien desarrolla clientes, el servidor sigue la especificación de autorización de MCP:

1. Una llamada sin autenticar responde `401` con `WWW-Authenticate: Bearer resource_metadata="https://api.brelio.app/.well-known/oauth-protected-resource/mcp"`.
2. Ese documento indica el servidor de autorización; Brelio usa WorkOS AuthKit, que admite Client ID Metadata Documents y registro dinámico de clientes.
3. Pide el token con `resource=https://api.brelio.app/mcp`. La audiencia del token debe ser exactamente esa dirección.

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

```json Respuesta 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"
}
```

Los tokens de acceso duran cinco minutos y el asistente los renueva. Cuando desconectas un asistente en Brelio, su acceso se corta en cinco minutos como máximo.

## Protege tus credenciales

* Guarda las claves y los client secrets en un gestor de secretos o en variables de entorno. Nunca los subas al repositorio, los pegues en un chat ni los pongas en una URL.
* Da a cada herramienta su propia clave, solo con los permisos que necesita, para poder revocar una sin tocar las demás.
* Las claves se validan con WorkOS y el resultado se guarda hasta 60 segundos, así que una clave revocada puede funcionar hasta un minuto.
* Cada llamada queda registrada con la credencial que la hizo. La clínica lo ve en **Configuración › Integraciones › Actividad**.


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