border.bot
Docs menu

API reference

Get started

Authentication

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

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 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 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 (RFC 9728) and authorization server metadata (RFC 8414).

Agents that register themselves should read 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.

Last updated