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

# Authentication

> Authenticate to the organization-scoped Arbol API with the security scheme declared by OpenAPI.

Send API credentials as an HTTP bearer token.

```http theme={null}
Authorization: Bearer <access-token>
```

The production OpenAPI document is authoritative for the active security schemes, issuer, token endpoint, and required scopes. Credentials are provisioned for approved organizations during onboarding.

## OAuth contract

The Auth0-based contract being rolled out defines two alternatives:

* `userOAuth` uses the authorization-code flow for a person acting in one organization. Each operation includes the baseline `org:use` scope plus its resource permissions.
* `machineOAuth` uses client credentials for an organization-bound service. Its grant must include every scope named by the operation.

<Warning>
  Do not assume an OAuth flow is active for your organization until Arbol confirms the rollout. If the live OpenAPI document exposes a different bearer scheme, follow that production contract and your onboarding instructions.
</Warning>

## Protected-resource metadata

OAuth clients can discover API resource metadata at:

```text theme={null}
https://api.getarbol.com/.well-known/oauth-protected-resource
```

On a `401` response, inspect the `WWW-Authenticate` header for the resource-metadata location.

## Token handling

* Never put a bearer token in a query parameter.
* Never forward an API token to the MCP endpoint. MCP uses its own audience and exchanges delegated authority for an API token.
* Request only the scopes your integration needs.
* Keep user tokens and machine credentials in separate storage and rotation policies.
* Treat `401` as an invalid or unusable credential and `403` as a verified credential without sufficient authority.