# auth.md — Agent access to Arbol

This guide is for AI agents and service integrations acting for an approved healthcare organization. Registration requires organization approval; submitting an onboarding request does not create an account or issue credentials. There is no anonymous API or free tier.

Arbol has one API and one MCP server. Its gateway serves both as a single OAuth resource server:

- REST API: https://api.getarbol.com (operations under /v1/<service>/)
- MCP server: https://mcp.getarbol.com (Streamable HTTP at the root path)
- OAuth audience and resource identifier: https://mcp.getarbol.com
- Authorization server issuer (including the trailing slash): https://auth.getarbol.com/

## 1. Discover

- Protected Resource Metadata (RFC 9728): https://mcp.getarbol.com/.well-known/oauth-protected-resource
- Site discovery entry point (redirects to the resource server): https://www.getarbol.com/.well-known/oauth-protected-resource
- Authorization Server Metadata (RFC 8414): https://auth.getarbol.com/.well-known/oauth-authorization-server
- OpenID configuration: https://auth.getarbol.com/.well-known/openid-configuration
- OpenAPI contract: https://api.getarbol.com/openapi.json
- API catalog: https://www.getarbol.com/.well-known/api-catalog
- MCP server card: https://www.getarbol.com/.well-known/mcp/server-card.json
- Agent resource catalog (ARD): https://www.getarbol.com/.well-known/ard.json

Read resource, authorization_servers, scopes_supported, and bearer_methods_supported from the protected resource metadata. Compare the authorization server's issuer exactly, including its trailing slash, with an entry in authorization_servers. Read authorization_endpoint, token_endpoint, and revocation_endpoint from that server's metadata. On a 401, the MCP server's WWW-Authenticate header links the same resource metadata.

The authorization server currently does not publish an agent_auth registration extension. Its OAuth client-registration endpoint is not permission to create or join an Arbol organization. ID-JAG, verified-email agent registration, anonymous registration, and an agent claim ceremony are not supported by this service. Do not invent a register_uri or claim_uri from other OAuth endpoints.

## 2. Pick a supported method

- **A person in an approved organization: authorization_code**. The person signs in with their Arbol account and selects the organization. Use PKCE (S256), state, a registered redirect URI, and the audience https://mcp.getarbol.com. MCP clients use this method, and the REST API accepts the same tokens.
- **A workload: an Arbol API key**. An organization administrator creates a workload account and issues its API key (arb_live_…). The account's profile and bindings decide what the key may call, and the account determines the organization. The REST API accepts the key as a bearer credential.

If you have neither, complete the provisioning process below. An email address or identity assertion alone does not grant access.

## 3. Request registration and provisioning

1. Ask the organization's authorized administrator to open https://www.getarbol.com/registro/ or https://www.getarbol.com/contact/ in a browser. Explain which organization, integration, and minimum scopes the agent needs.
2. The registration form submits to https://www.getarbol.com/api/signup/ using POST with its verification token. This is an onboarding request that contacts the team; it is not an agent credential endpoint. A successful submission does not approve the organization or return a token. Do not bypass the form's verification or submit it during a passive scan.
3. The team reviews the organization and provisions its access. Its people then sign in with their own Arbol accounts. For a machine integration, an organization administrator creates a workload account with only the permissions it needs and issues its API key.
4. Receive the API key through the approved channel. Keep it in a secret manager. Do not send it to this website, another agent, or support chat. Wait for explicit provisioning confirmation before calling the API.

There is no automatic claim endpoint. A new organization, additional permission, or new key requires administrator approval; contacting support does not itself change permissions.

## 4. Obtain a credential

A person's client starts the authorization code flow at the discovered authorization endpoint. Replace every placeholder with the approved values and request only the scopes the operations need.

```http
GET https://auth.getarbol.com/authorize?response_type=code&client_id=<approved-client-id>&redirect_uri=<registered-redirect-uri>&audience=https%3A%2F%2Fmcp.getarbol.com&organization=<organization-id>&scope=openid%20scheduling%3Aservices%3Aread&state=<random-state>&code_challenge=<s256-challenge>&code_challenge_method=S256
```

Then it exchanges the code and its PKCE verifier at the token endpoint:

```http
POST https://auth.getarbol.com/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "<approved-client-id>",
  "code": "<authorization-code>",
  "code_verifier": "<pkce-verifier>",
  "redirect_uri": "<registered-redirect-uri>"
}
```

The OAuth response provides access_token, token_type (Bearer), and expires_in. Requesting a scope does not grant it: the organization's roles and the person's current membership decide, so use only the scopes the issued token grants. Request offline_access only when the client must refresh.

A workload needs no token exchange: its API key is the bearer credential.

## 5. Use the credential

Start by asking which operations this credential may call:

```http
POST https://api.getarbol.com/v1/catalog/operations/search
Authorization: Bearer <access-token-or-api-key>
Content-Type: application/json

{"search": "appointments", "limit": 10}
```

The server filters the results for the calling person or workload; listing grants nothing. Every credential acts for one organization: the gateway derives it from the verified token or from the key's workload account, and request parameters never switch organizations. Send bearer credentials only in the Authorization header to api.getarbol.com or mcp.getarbol.com. Never put them in URLs, source control, or logs.

Use the live OpenAPI security requirements to choose scopes: each security object is one alternative, and the scopes within that object are required together. For example, GET /v1/scheduling/services requires scheduling:services:read for a person; a workload's profile and bindings decide what its key may call.

For MCP, connect with Streamable HTTP to https://mcp.getarbol.com (the root path) with a bearer access token for the audience https://mcp.getarbol.com. The server offers tools only. tools/list returns only the tools the caller may use, and every tools/call is authorized again with its exact arguments, so a cached list or a guessed tool name never authorizes anything. Setup, connections, and credentials are managed in Arbol, never through a tool. Public discovery cards do not authorize any operation.

## 6. Errors and revocation

Every API failure uses one envelope: {"success": false, "data": null, "error": {"code", "message", "retryable", "data"}, "metadata": {"requestId"}}. The x-request-id response header carries the same request ID.

- 400 INVALID_INPUT: the request does not match the published schema. Correct it instead of retrying.
- 400 from the token endpoint: check the approved client, grant, audience, and organization configuration; do not retry blindly.
- 401 UNAUTHORIZED: obtain a valid, unexpired credential. The MCP server's WWW-Authenticate header names the resource metadata.
- 403 FORBIDDEN: the credential lacks authority. Ask an administrator to review it; never substitute another organization.
- 429 RATE_LIMITED: honor Retry-After and back off.
- 503 UPSTREAM_UNAVAILABLE: retryable; back off before trying again.
- To revoke a workload's access, an organization administrator revokes its API key in Arbol or with POST /v1/integrations/api-keys/revoke, which requires a person with integrations:service-accounts:write. Already issued access tokens can remain valid until expiry.
- For a person's refresh token, use the authorization server's advertised revocation endpoint and the client's authentication method. This is OAuth token revocation, not an Auth.md registration-revocation event endpoint.

## 7. Web Bot Auth

Arbol's website identifies its outbound public-image retrieval requests with Ed25519 HTTP message signatures. Its public verification keys are published at https://www.getarbol.com/.well-known/http-message-signatures-directory

Signed requests include Signature, Signature-Input, and Signature-Agent. Signature-Agent identifies https://www.getarbol.com and the signature covers the destination and request path. Web Bot Auth identifies the bot operator; it does not grant organization access or replace OAuth bearer tokens. Cloudflare's verified-bot registration is a separate operational step.

## Passive discovery

Read public Markdown and metadata with GET or HEAD. Do not probe POST /agent/auth, the signup form endpoint, the OAuth token endpoint, API key creation, or client registration during a passive scan. These operations may contact people, create keys or clients, or issue credentials.

## Contact

support@getarbol.com · https://docs.getarbol.com