# border.bot auth.md

> How AI agents authenticate with border.bot: OAuth 2.1 for the MCP server, workspace API keys for the REST API.

## Who this is for

AI agents and MCP clients that want to classify products, calculate landed cost or check country of origin with border.bot on behalf of a person or a business.

## Option 1: MCP server with OAuth (agents acting for a person)

- Resource: `https://api.border.bot/mcp` (Streamable HTTP). An unauthenticated request returns `401` with a `WWW-Authenticate` header naming the resource metadata.
- Protected resource metadata (RFC 9728): https://api.border.bot/.well-known/oauth-protected-resource/mcp (also at https://border.bot/.well-known/oauth-protected-resource)
- Authorization server metadata (RFC 8414): https://api.border.bot/.well-known/oauth-authorization-server (issuer `https://api.border.bot`)
- Register your client yourself: dynamic client registration (RFC 7591) at `POST https://api.border.bot/oauth/register`, or use an OAuth client ID metadata document (a URL as your `client_id`).
- Flow: authorization code with PKCE (`S256`). The person signs in to border.bot and approves the workspace; your client gets an access token (1 hour) and a refresh token.
- Scopes: `mcp:read` (read tools), `mcp:write` (tools that spend credits), `offline_access` (refresh tokens).
- Send the token as `Authorization: Bearer <access token>` on every MCP request.

## Option 2: REST API key (server-side integrations)

- A person creates a workspace API key in the dashboard (https://app.border.bot/developers?tab=keys) and gives it to the integration. Keys start with `bb_live_`, can be limited to scopes and can expire.
- Agents cannot create API keys themselves, and there is no anonymous or email-claim registration.
- Send it as `Authorization: Bearer bb_live_…` to `https://api.border.bot/v1/…`. Scopes and errors: https://border.bot/docs/authentication.md

## Without credentials

`GET https://api.border.bot/v1/countries`, `GET https://api.border.bot/v1/pricing` and `GET https://api.border.bot/v1/classify/modes` are public. The free web tools on https://border.bot/tools allow a few runs per visitor in a browser.

## Revoking access

People revoke MCP grants and API keys in the dashboard. Revoked API keys answer `401` immediately.

## Billing

Calls that run the engine spend the workspace’s prepaid credits (prices: https://api.border.bot/v1/pricing). Failed calls are refunded. Docs: https://border.bot/docs