Burrowbox Docs

Authentication

Burrowbox uses bearer tokens in the Authorization header.

Authorization: Bearer <token>
Token Prefix Scope Where to get it
API key tmk_ Everything your account can do: machines, billing, platform MCP Dashboard → Account → API keys
Machine token tmm_ Only that machine's MCP endpoint and live-view links mcpToken in the machine response
OAuth access token tmo_ Same as an API key, for an app you approved An MCP client signing in for you (see OAuth)
Session cookie — The dashboard in your browser Signing in

#API keys

API keys act as your user. Keep them on your server. Create one key per integration so you can revoke them independently; the dashboard shows when each key was last used.

#Machine tokens

A machine token only works on two endpoints, and only for its own machine: POST /api/machines/{id}/mcp and POST /api/machines/{id}/live-view (so an agent can share its screen; see Embed the live view). It can't list, create, stop or bill anything. This is the token to hand to an agent, including agents acting for your customers.

#OAuth for MCP clients

MCP clients that support OAuth (Claude, Cursor, VS Code, the MCP SDKs) can connect to https://burrowbox.dev/mcp with no API key. Add the URL, and the client opens a Burrowbox page where you sign in and click Allow. Every app you approve is listed under Account → Connected apps, where you can disconnect it at any time.

claude mcp add --transport http burrowbox https://burrowbox.dev/mcp

Burrowbox follows the MCP authorization spec. If you're building a client:

Discovery A 401 from /mcp carries WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". Authorization server metadata is at /.well-known/oauth-authorization-server.
Registration Dynamic client registration at POST /oauth/register, or use a client ID metadata document (an https URL as the client_id).
Authorization GET /oauth/authorize with response_type=code, PKCE (S256 required), state, and optionally resource. Redirect URIs must be https, loopback http (any port), or an app scheme.
Tokens POST /oauth/token with authorization_code or refresh_token. Access tokens last 1 hour; refresh tokens last 30 days and rotate on each use. Revoke with POST /oauth/revoke.
Scope account: the token acts as you, like an API key.

#Accounts

These endpoints power the dashboard. Browser requests must come from the Burrowbox origin.

Method Path Body
POST /api/auth/register email, password, name Creates the account and signs in. A confirmation email is sent.
POST /api/auth/login email, password Signs in (sets the session cookie)
POST /api/auth/logout — Signs out this session
POST /api/auth/verify token Confirms the email address from the link in the email. The welcome credit is added once the email is confirmed and a card is saved.
POST /api/me/verify-email — Sends a new confirmation email (signed in)
POST /api/auth/forgot email Emails a password-reset link. Always returns {"ok": true}, so it can't be used to find out which emails have accounts.
POST /api/auth/reset token, password Sets a new password from the reset link, signs out every other session, and signs you in

Links in emails are single-use: confirmation links last 24 hours and reset links last 1 hour. Only a hash of each link is stored. Changing or resetting a password also sends a security notice to the account's address.

#Rate limits

Sign-in and sign-up are rate-limited per IP address and per email. API calls are not metered by count, only by machine time.

#Security notes