---
title: "Quickstart"
description: "Make your first authenticated call to the Arbol API with an API key and 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.

# Quickstart

This page takes you from a new API key to a successful call. The call is [Get the current organization](/api/account/organization/get/), a read that changes nothing and answers with the organization your key belongs to.

You need `curl` and access to Arbol Account with permission to create API keys.

## Make the call

1. **Create an API key.** In Arbol Account, [create an API key](/en/account/api-keys/) and give it the `account:organizations:read` scope, the only one this call needs. The key starts with `arb_live_` and is shown only once, so copy it into your secret manager.

2. **Load the key into your shell.** Read it from the terminal rather than typing it into a command, so it stays out of your shell history. Paste the key and press Enter:

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

3. **Call the API.** Send the key as a bearer token in the `Authorization` header:

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

## Read the response

A successful call answers `200` with a JSON envelope. The values below are illustrative; yours describe your organization:

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

| Field | What it tells you |
| --- | --- |
| `success` | `true` for a success, `false` for an error. |
| `data` | The result. Here: the organization's `id`, `name` and `slug`, each Arbol product with whether the organization has it, and the caller's permissions in Account. |
| `error` | `null` on success. On failure, an object with `code`, `message`, `retryable` and `data`. |
| `metadata.requestId` | The request's id, also sent as the `X-Request-Id` header. Keep it when you report a problem. |

Operations answer in this envelope whether they succeed or fail. See [Responses and errors](/en/developers/concepts/responses-and-errors/).

## If it fails

| Status | `error.code` | What to check |
| --- | --- | --- |
| `401` | `UNAUTHORIZED` | The key is missing, mistyped, rotated or deleted, or it was sent somewhere other than the `Authorization` header. |
| `403` | `FORBIDDEN` | The key is valid but lacks the `account:organizations:read` scope. |
| `429` | `RATE_LIMITED` | Too many requests. Wait the number of seconds in the `Retry-After` header. |

Run `curl` with `--include` to see the status line and the `X-Request-Id` header.

## What just happened

- **One host.** Every service lives under `https://api.getarbol.com/v1/<service>/`. This call went to the Account service.
- **One credential.** The key is the only credential the request carried, in the `Authorization` header. The same key works for every service, as far as its scopes allow.
- **One organization.** The key belongs to one organization, and every call it makes acts in that organization. The response named it.

## Next steps

- **Authentication** — API keys, OAuth tokens, scopes, and how to handle keys safely.
- **Organizations** — The organization boundary, people and machines, and permissions.
- **Pagination** — Read long lists a page at a time with cursors.
- **Retries** — Which calls are safe to repeat, and what to do when a write's outcome is unknown.

To find more operations, browse the [Account API reference](/api/account/) or connect an AI client through [MCP](/en/developers/mcp/).

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