Inicio rápido | Arbol AI Docs

Esta página te lleva de una API key nueva a una llamada exitosa. La llamada es Obtener la organización actual, una lectura que no cambia nada y responde con la organización a la que pertenece tu key.

Necesitas curl y acceso a Cuenta de Arbol con permiso para crear API keys.

Hacer la llamada

Crea una API key. En Cuenta de Arbol, crea una API key y dale el permiso (scope) account:organizations:read, el único que necesita esta llamada. La key empieza por arb_live_ y se muestra una sola vez, así que cópiala en tu gestor de secretos.
Carga la key en tu shell. Léela desde la terminal en lugar de escribirla en un comando, para que no quede en el historial de tu shell. Pega la key y presiona Enter:
```
read -rs ARBOL_API_KEY && export ARBOL_API_KEY
```

Llama a la API. Envía la key como token bearer en el encabezado Authorization:

curl https://api.getarbol.com/v1/account/organization \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Leer la respuesta

Una llamada exitosa responde 200 con un envoltorio (envelope) JSON. Los valores de abajo son ilustrativos; los tuyos describen tu organización:

{
  "success": true,
  "data": {
    "id": "org_EXAMPLE000000001",
    "name": "Example Clinic",
    "logoUrl": null,
    "current": true,
    "slug": "example-clinic",
    "colors": { "primary": null, "pageBackground": null },
    "applications": [
      { "id": "raiz", "enabled": true, "roles": [], "administers": false },
      { "id": "agenda", "enabled": true, "roles": [], "administers": false },
      { "id": "ambar", "enabled": false, "roles": [], "administers": false },
      { "id": "account", "enabled": true, "roles": [], "administers": false }
    ],
    "permissions": ["account:organizations:read"]
  },
  "error": null,
  "metadata": { "requestId": "00000000-0000-4000-8000-000000000001" }
}

Campo	Qué te dice
`success`	`true` si tuvo éxito, `false` si hubo un error.
`data`	El resultado. Aquí: el `id`, el `name` y el `slug` de la organización, cada producto de Arbol con la indicación de si la organización lo tiene, y los permisos de quien llama en Cuenta.
`error`	`null` si tuvo éxito. Si falla, un objeto con `code`, `message`, `retryable` y `data`.
`metadata.requestId`	El id de la solicitud, que también llega en el encabezado `X-Request-Id`. Guárdalo para cuando reportes un problema.

Las operaciones responden con este envoltorio tanto si tienen éxito como si fallan. Consulta Respuestas y errores.

Si falla

Estado	`error.code`	Qué revisar
`401`	`UNAUTHORIZED`	Falta la key, está mal escrita, fue rotada o eliminada, o se envió en un lugar distinto del encabezado `Authorization`.
`403`	`FORBIDDEN`	La key es válida pero no tiene el scope `account:organizations:read`.
`429`	`RATE_LIMITED`	Demasiadas solicitudes. Espera los segundos que indica el encabezado `Retry-After`.

Ejecuta curl con --include para ver la línea de estado y el encabezado X-Request-Id.

Qué acaba de pasar

Un host. Todos los servicios viven bajo https://api.getarbol.com/v1/<service>/. Esta llamada fue al servicio de Cuenta.
Una credencial. La key fue la única credencial que llevó la solicitud, en el encabezado Authorization. La misma key funciona para todos los servicios, hasta donde sus scopes lo permitan.
Una organización. La key pertenece a una organización, y cada llamada que hace actúa en esa organización. La respuesta la nombró.

Siguientes pasos

Autenticación

API keys, tokens de OAuth, scopes y cómo manejar las keys con seguridad.

Organizaciones

El límite entre organizaciones, las personas y las máquinas, y los permisos.

Paginación

Lee listas largas página por página con cursores.

Reintentos

Qué llamadas es seguro repetir y qué hacer cuando no se sabe el resultado de una escritura.

Para encontrar más operaciones, explora la referencia de la API de Cuenta o conecta un cliente de IA a través de MCP.