Authentication & scopes

Bearer token

Send the platform API secret as a Bearer token on every request:

Authorization: Bearer <platform_api_secret>

Treat the secret like a password: use TLS, store it in a vault or env vars, and rotate it if exposed.

Your workspace

The credential is issued for your Fleet workspace. Catalog, users, devices, carts, and orders are always scoped to that workspace. You do not pass a workspace ID in requests.

READ vs WRITE

Scope	What you can do
READ	All GET operations (catalog, carts, orders, users, devices).
WRITE	Everything READ can do, plus POST / PATCH / DELETE on carts (including validate), users, and devices.

Calling a mutation with a READ key returns { "error": "INSUFFICIENT_SCOPE" } (status code depends on operation).

Rate limits (platform API)

From the live configuration of the platform route limiter:

Environment	Window	Max requests (per window)	How it is counted
Production	1 minute	100	Primarily per platform API credential (after your key is recognized).
Sandbox	1 minute	300	Same idea: per credential in normal authenticated traffic.

Responses may include standard RateLimit-* headers. If the limit is exceeded, the API returns 429.

Availability: Rate limiting depends on Fleet’s counter backend. If it is unavailable, the gateway may return 503. Retry with short backoff.

See also

• Installation — obtaining a key.
• Requests & responses — JSON shapes and validation errors.
• API reference — security and errors per operation.