# Authentication & scopes

## Bearer token

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

```http
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](./installation/) — obtaining a key.
- [Requests & responses](./requests-and-responses/) — JSON shapes and validation errors.
- **API reference** — security and errors per operation.