---
title: "Autenticación"
description: "Las credenciales que acepta la API de Arbol, cómo enviarlas y cómo los scopes deciden qué puede hacer cada llamada."
---

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

# Autenticación

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](/developers/mcp/), y siempre actúa en una [organización](/developers/concepts/organizations/).

## Credenciales

| Credencial | Quién llama | Cómo la obtienes |
| --- | --- | --- |
| API key, `arb_live_…` | Una máquina | La [creas en Cuenta de Arbol](/account/api-keys/). 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

```http
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](/api/account/permissions/list/) 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](/api/account/roles/list/) muestra los permisos de cada rol.

### Qué exige cada operación

La página de cada operación en la [referencia de la API](/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](/api/account/api-keys/list/) 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](/developers/concepts/organizations/#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](https://www.rfc-editor.org/rfc/rfc9728)), que no necesitan credencial:

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

```json
{
  "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`:

```http
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](/developers/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](/api/account/api-keys/create/).
- **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](/api/account/api-keys/create/), y las keys que listas lo muestran en UTC.
- **Rota y elimina.** [Rotar una API key](/api/account/api-keys/rotate/) le da un secreto nuevo, y el anterior deja de funcionar en unos dos minutos. [Eliminar una API key](/api/account/api-keys/delete/) también rechaza, en unos dos minutos, los tokens que ya había obtenido.

Source: https://docs.getarbol.com/developers/authentication/index.mdx