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
- Requests authenticated by the session cookie must come from the Burrowbox origin; cross-site requests are rejected.
- Tokens are stored hashed. If you lose an API key, revoke it and create a new one.