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 environment variables, and rotate it if it leaks.

Your workspace

The credential is issued for your Fleet workspace. Catalog results, users, devices, carts, and orders are always the ones that belong to that workspace. You do not select a “workspace id” in the request—the key implies it.

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 an error body such as { "error": "INSUFFICIENT_SCOPE" } (see API reference for the exact status code per route).

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, you get 429 with a short message asking you to retry later.

Availability: Rate limiting relies on Fleet’s backing store for counters. If that service is unavailable, the gateway may respond with 503 and a message such as rate limiting being temporarily unavailable—in that case retry after a short backoff.

See also

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