Autenticación | Arbol AI Docs

Cada llamada a la API lleva exactamente una credencial, como token bearer en el encabezado Authorization. Una credencial funciona para todos los servicios, por REST y por MCP, y siempre actúa en una organización.

Credenciales

Credencial	Quién llama	Cómo la obtienes
API key, `arb_live_…`	Una máquina	La creas en Cuenta de Arbol. Se muestra una vez, cuando se crea.
Token de client credentials	Una máquina	Una aplicación de máquina creada en Cuenta de Arbol lo pide a `https://auth.getarbol.com/oauth/token` con el flujo (grant) de client credentials.
El token de acceso de una persona, como su sesión en una app	Una persona	La persona inicia sesión en el servidor de autorización de Arbol con el flujo de código de autorización (`https://auth.getarbol.com/authorize`), con una organización seleccionada. Un servicio que actúa en nombre de la persona presenta el token que obtuvo por ella.

Los tokens los emite el servidor de autorización de Arbol, https://auth.getarbol.com/, para la audiencia https://api.getarbol.com. Una API key es la credencial más simple para un servidor: la envías tal cual en cada llamada, sin pedir ni renovar tokens.

Enviar la credencial

GET /v1/account/organization HTTP/1.1
Host: api.getarbol.com
Authorization: Bearer arb_live_…

La API lee las credenciales solo del encabezado Authorization. Una solicitud que lleve una en la query string (access_token, api_key) o en un encabezado X-Api-Key se rechaza con 401.

Permisos (scopes)

Un permiso (scope) indica lo que puede hacer una credencial, con la forma <service>:<resource>:<access>: account:organizations:read, agenda:bookings:write.

Una API key lleva los scopes que se eligieron al crearla, que deben ser scopes que tiene quien la crea. Listar los permisos de la plataforma muestra cuáles puedes dar.
El token de una aplicación de máquina lleva los scopes que se le otorgaron a la aplicación.
El token de una persona cuenta un scope solo hasta donde los roles de la persona lo otorgan. Listar los roles de cada producto muestra los permisos de cada rol.

Qué exige cada operación

La página de cada operación en la referencia de la API lo dice debajo de su descripción:

Scope (o Scopes) lista los permisos que admiten la operación; basta con tener uno de ellos. Muchas lecturas también aceptan el scope de escritura correspondiente: Listar las API keys acepta account:api-keys:read o account:api-keys:write. Otras aceptan solo el scope de lectura, así que revisa cada operación. Cuando algunas entradas necesitan un scope adicional, la línea dice cuál.
Credentials dice si la operación acepta API keys y tokens de client credentials, o solo el token de una persona con sesión iniciada. Consulta Personas y máquinas.

Si generas un cliente a partir del documento OpenAPI, la misma regla está en el security de cada operación, con tres esquemas: arbolApiKey (API key), arbolMachine (token de client credentials) y arbolHuman (token de una persona). Basta con cualquiera de las alternativas, y una operación que lista solo arbolHuman acepta solo el token de una persona.

Descubrimiento de OAuth

Un cliente OAuth encuentra el servidor de autorización de Arbol a partir de los metadatos de recurso protegido de la API (RFC 9728), que no necesitan credencial:

curl https://api.getarbol.com/.well-known/oauth-protected-resource

{
  "resource": "https://api.getarbol.com",
  "authorization_servers": ["https://auth.getarbol.com/"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["account:api-keys:read", "account:api-keys:write"],
  "resource_name": "Arbol API"
}

Aquí scopes_supported está abreviado: lista todos los scopes que exige alguna herramienta MCP. Un 401 remite a los clientes a este documento en su encabezado WWW-Authenticate:

WWW-Authenticate: Bearer resource_metadata="https://api.getarbol.com/.well-known/oauth-protected-resource"

El cliente lee los metadatos del servidor de autorización, inicia la sesión de la persona para el recurso https://api.getarbol.com y repite la solicitud con el token. Así es como inician sesión los clientes MCP.

401 o 403

Estado	`error.code`	Significado	Qué hacer
`401`	`UNAUTHORIZED`	No hay una credencial válida: falta, está mal formada, venció o fue revocada, o no se envió en el encabezado `Authorization`.	Envía una credencial válida. Obtén un token nuevo o revisa la key.
`403`	`FORBIDDEN`	La credencial es válida pero no autoriza esta operación. No tiene ninguno de los scopes de la operación, la operación acepta solo personas, o las restricciones de una API key dejan fuera la operación o la conexión.	Usa una credencial que tenga uno de los scopes de la operación.

Ninguno es retryable: repetir la misma solicitud con la misma credencial obtiene la misma respuesta.

Manejo seguro de las API keys

Guarda las keys en un gestor de secretos. Una key se muestra una vez, cuando se crea o se rota, y listar las keys nunca vuelve a mostrarlas.
Nunca pongas una credencial en una URL. Las URL terminan en logs y en el historial del navegador, y la API rechaza las credenciales ahí.
Nunca expongas una API key en un navegador. Una página web puede llamar a la API, que admite cualquier origen, pero debe hacerlo con el token propio de la persona que inició sesión.
Otorga el mínimo privilegio. Dale a cada sistema su propia key, solo con los scopes que necesita. Una key también se puede restringir, por integración, a algunas operaciones y conexiones: consulta restrictions en Crear una API key.
Usa keys que vencen. Una key deja de funcionar en la fecha que eliges al crearla, por defecto siete días después: es expiresAt en Crear una API key, y las keys que listas lo muestran en UTC.
Rota y elimina. Rotar una API key le da un secreto nuevo, y el anterior deja de funcionar en unos dos minutos. Eliminar una API key también rechaza, en unos dos minutos, los tokens que ya había obtenido.