# Authentication

> Authenticate border.bot REST calls with a workspace API key and scopes, and MCP clients with OAuth 2.1.

Source: https://border.bot/docs/authentication
Last updated: 2026-10-09

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.


## API keys

REST calls authenticate with a workspace API key in the `Authorization` header:

```http
Authorization: Bearer bb_live_...
```

Create and revoke keys in the [dashboard](https://app.border.bot/developers?tab=keys) under **Developers → API keys**. A key is shown once and stored only as a hash, so a lost key can't be recovered: revoke it and create another. A key can also have an expiry date.

A missing or invalid key gets `401 unauthorized` with a `WWW-Authenticate: Bearer` header.

## Scopes

A key has full access, or only the scopes you pick when you create it. Each endpoint in the [reference](https://border.bot/docs/api) names the scope it needs. A key without that scope gets `403 forbidden` with `details.reason` set to `missing_scope`, and the message says which scope is missing.

| Scope | Allows |
| --- | --- |
| `classify` | Classification: Classify products (single and batch), agency product codes, and feedback on answers. |
| `calculate` | Landed cost: Landed cost for a line or a whole shipment, and duty stacking. |
| `origin` | Products and origin: Read product pages and work out or check the country of origin. |
| `compliance` | Compliance checks: Restricted goods checks and denied-party screening, with the screening history. |
| `bulk` | Bulk runs: Start, follow and cancel bulk runs. A run also needs the scope of what it runs: Classification, or Landed cost. |
| `settings` | Workspace rules: Read and change blocked codes and restriction rules. |
| `account` | Account: Credit balance, ledger and usage history. |

`GET /v1/me` works with any key and reports its `scopes` and `expiresAt`.

## Endpoints without a key

These reference endpoints are public and rate limited per IP address:

- `GET /v1/countries`: destinations and what each one supports.
- `GET /v1/pricing`: what every action costs in credits.
- `GET /v1/classify/modes`: the classification modes you can choose.

## MCP clients: OAuth 2.1

The MCP server at `https://api.border.bot/mcp` doesn't take API keys. MCP clients sign the user in with OAuth 2.1 (authorization code with PKCE `S256`):

- Clients can register themselves with dynamic client registration (`POST https://api.border.bot/oauth/register`, RFC 7591) or use a client ID metadata document.
- Scopes: `mcp:read` to read, `mcp:write` to run actions that spend credits.
- Discovery: [protected resource metadata](https://api.border.bot/.well-known/oauth-protected-resource/mcp) (RFC 9728) and [authorization server metadata](https://api.border.bot/.well-known/oauth-authorization-server) (RFC 8414).

Agents that register themselves should read [auth.md](https://border.bot/auth.md).

## Keeping keys safe

- Call the API from your server, never from a browser or a mobile app.
- Give each integration its own key with only the scopes it needs, so you can revoke one without breaking the others.
- Every call is in the workspace's request log (`GET /v1/requests`, 30 days), with the key that made it.