---
title: "Inicio rápido"
description: "Haz tu primera llamada autenticada a la API de Arbol con una API key y curl."
---

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

# Inicio rápido

Esta página te lleva de una API key nueva a una llamada exitosa. La llamada es [Obtener la organización actual](/api/account/organization/get/), 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

1. **Crea una API key.** En Cuenta de Arbol, [crea una API key](/account/api-keys/) 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.

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

   ```bash
   read -rs ARBOL_API_KEY && export ARBOL_API_KEY
   ```

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

   ```bash
   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:

```json
{
  "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](/developers/concepts/responses-and-errors/).

## 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](/api/account/) o conecta un cliente de IA a través de [MCP](/developers/mcp/).

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