Authentication

API Keys

The FreightCake API uses Bearer token authentication. Include your API key in the Authorization header of every request:

curl https://api.freightcake.com/api/v1/quotes \
  -H "Authorization: Bearer fk_live_abc123..."

Key Format

API keys follow the format fk_{mode}_{48 hex characters}:

fk_live_... — Production key (live carrier rates, real shipments)
fk_test_... — Test key (sandbox mock carriers, isolated data)

Creating Keys

Log into the FreightCake dashboard
Go to Settings → API Keys
Click Create API Key
Choose the permissions (scopes) for this key
Copy the key immediately — it won't be shown again

Key Security

Never expose API keys in client-side code (browsers, mobile apps)
Store keys in environment variables or a secrets manager
Rotate keys immediately if compromised via the dashboard
Use test keys during development, live keys only in production

Permissions

API keys can be scoped to specific operations:

Scope	Description
`quotes.read`	List and retrieve quotes
`quotes.write`	Create new quotes
`shipments.read`	List and retrieve shipments
`shipments.write`	Create, update, and cancel shipments
`tracking.read`	View tracking information
`tracking.write`	Create and refresh tracking
`invoices.read`	List and retrieve invoices
`webhooks.read`	List and manage webhook endpoints
`webhooks.write`	Create and update webhook endpoints

Rate Limits

API requests are rate-limited per key:

Tier	Limit
Standard	100 requests / minute
Burst	20 requests / second

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Responses

Invalid or missing authentication returns a 401 status:

{
  "error": {
    "type": "authentication_error",
    "message": "Missing or invalid API key. Include your key in the Authorization header: Bearer fk_live_...",
    "doc_url": "https://docs.freightcake.com/api/authentication"
  }
}