# Freightbox authentication

Freightbox uses scoped API keys for its Platform Email API and authenticated action MCP. Its separate public documentation MCP is read-only and needs no API key. Freightbox does not support OAuth, autonomous agent registration, or the WorkOS agent_auth registration flow today. A human organization administrator must create, restrict, rotate, and revoke every credential used for customer data or actions.

## Discover

- Developer guide: https://getfreightbox.com/developers
- OpenAPI 3.1: https://api.getfreightbox.com/api/v1/platform/openapi.json
- API reference: https://api.getfreightbox.com/api/v1/platform/docs
- Experimental MCP Server Card: https://getfreightbox.com/mcp/server-card
- MCP endpoint: https://api.getfreightbox.com/mcp
- Experimental public documentation MCP Server Card: https://getfreightbox.com/mcp/docs/server-card
- Public documentation MCP endpoint: https://api.getfreightbox.com/mcp/docs

## Pick a method

Use a Freightbox API key for the Platform API or action MCP. REST and action MCP use separate scope families, so choose the interface first and request only its narrowest necessary scopes. Prefer a read-only credential for agents that inspect untrusted inbound email. The public documentation MCP needs no credential and cannot access organization data or perform actions.

## Register

Self-registration is unavailable. There is no register_uri or agent_auth endpoint, and Freightbox does not accept an identity_assertion or id-jag token. Ask a human organization administrator to create a key in Freightbox API Key settings and, when possible, restrict it to specific inbox IDs.

## Claim

No autonomous claim exchange exists. The administrator must deliver the plaintext key through an approved secret-management channel. Freightbox displays the secret once. Never ask a user to paste it into a public page, chat prompt, URL, source repository, or log.

## Use the credential

Send the key on every authorized request:

    Authorization: Bearer YOUR_FREIGHTBOX_API_KEY

Platform API scopes are platform:inbox:read, platform:inbox:write, platform:identity:read, platform:identity:write, and platform:message:send. MCP scopes are inbox:read, inbox:write, and inbox:send.

## Errors

A missing, invalid, expired, or revoked key returns an authentication error. An insufficient scope or disallowed inbox returns an authorization error. Freightbox does not currently advertise OAuth resource_metadata in WWW-Authenticate, so clients must not invent an OAuth redirect or registration flow. Respect 429 responses and their retry or rate-limit information.

## Revocation

An organization administrator can revoke the key in Freightbox settings. Rotate it immediately if it appears in a prompt, log, repository, URL, screenshot, or any other untrusted location. Update the consuming service through its secret manager; never publish the replacement.