Authentication | Arbol AI Docs

Every API call carries exactly one credential, as a bearer token in the Authorization header. One credential works for every service, over REST and MCP, and always acts in one organization.

Credentials

Credential	Caller	How you get it
API key, `arb_live_…`	A machine	Create it in Arbol Account. It’s shown once, when it’s created.
Client-credentials token	A machine	A machine application created in Arbol Account requests it from `https://auth.getarbol.com/oauth/token` with the client credentials grant.
A person’s access token, such as their session in an app	A person	The person signs in to Arbol’s authorization server with the authorization code flow (`https://auth.getarbol.com/authorize`), with an organization selected. A service acting for the person presents the token it obtained on their behalf.

Tokens are issued by Arbol’s authorization server, https://auth.getarbol.com/, for the audience https://api.getarbol.com. An API key is the simplest credential for a server: you send it as it is on every call, with no tokens to request or renew.

Send the credential

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

The API reads credentials only from the Authorization header. A request that carries one in the query string (access_token, api_key) or in an X-Api-Key header is refused with 401.

Scopes

A scope names what a credential may do, as <service>:<resource>:<access>: account:organizations:read, agenda:bookings:write.

An API key carries the scopes chosen when it was created, which must be scopes its creator holds. List the platform permissions shows which ones you can give.
A machine application’s token carries the scopes the application was granted.
A person’s token counts a scope only as far as the person’s roles grant it. List the roles of each product shows each role’s permissions.

What each operation requires

Each operation’s page in the API reference says it under its description:

Scope (or Scopes) lists the scopes that admit the operation; holding any one of them is enough. Many reads also accept the matching write scope: List the API keys accepts account:api-keys:read or account:api-keys:write. Others accept only the read scope, so check each operation. When some inputs need a further scope, the line says which.
Credentials says whether the operation accepts API keys and client-credentials tokens, or only a signed-in person’s token. See People and machines.

If you generate a client from the OpenAPI document, the same rule is in each operation’s security, with three schemes: arbolApiKey (API key), arbolMachine (client-credentials token) and arbolHuman (a person’s token). Any one alternative is enough, and an operation that lists only arbolHuman accepts only a person’s token.

OAuth discovery

An OAuth client finds Arbol’s authorization server from the API’s protected resource metadata (RFC 9728), which needs no credential:

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

scopes_supported is shortened here: it lists every scope that some MCP tool requires. A 401 points clients to this document in its WWW-Authenticate header:

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

The client reads the authorization server’s metadata, signs the person in for the resource https://api.getarbol.com, and repeats the request with the token. This is how MCP clients sign in.

401 or 403

Status	`error.code`	Meaning	What to do
`401`	`UNAUTHORIZED`	No valid credential: it’s missing, malformed, expired or revoked, or it wasn’t sent in the `Authorization` header.	Send a valid credential. Get a new token, or check the key.
`403`	`FORBIDDEN`	The credential is valid but doesn’t authorize this operation. It holds none of the operation’s scopes, the operation accepts only people, or an API key’s restrictions leave the operation or connection out.	Use a credential that holds one of the operation’s scopes.

Neither is retryable: repeating the same request with the same credential gets the same answer.

Handle keys safely

Store keys in a secret manager. A key is shown once, when it’s created or rotated, and listing keys never shows them again.
Never put a credential in a URL. URLs end up in logs and browser history, and the API refuses credentials there.
Never ship an API key to a browser. A web page can call the API, which allows any origin, but it should do so with the signed-in person’s own token.
Grant the least privilege. Give each system its own key with only the scopes it needs. A key can also be restricted, per integration, to some operations and connections: see restrictions in Create an API key.
Use keys that expire. A key stops working at the date you choose when you create it, seven days later by default: it’s expiresAt in Create an API key, and listed keys show it in UTC.
Rotate and delete. Rotate an API key gives it a new secret, and the old one stops working within about two minutes. Delete an API key also refuses the tokens it already obtained within about two minutes.