# Authentication

> API keys, scopes, and how to keep them safe.

Source: https://docs.delivr.no/authentication/

Every request carries an API key as a bearer token:

```http
Authorization: Bearer dmk_3J9xT2…
```

Delivr issues your keys; see [Get sandbox access](/sandbox/#get-sandbox-access). Each key is shown once, when it is created, so store it in a secret manager straight away. Sandbox and production keys are separate, and a key only ever sees its own merchant's stores and orders.

## Scopes

A key has one of two scopes. Give each system the narrowest one it needs.

| Scope    | Allows                                                                       | Typical use                                                   |
| -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `quotes` | `GET /availability`, `GET /locations`, `GET /locations/{id}`, `POST /quotes` | The backend of a checkout widget that only prices deliveries. |
| `orders` | Everything: quotes, locations, orders, cancellations and webhooks            | Your order system or checkout backend that books deliveries.  |

A call outside the key's scope answers `403 insufficient_scope`.

## Keep keys server-side

Keys are for servers only. Never put one in a browser, a mobile app or a public repository: anyone holding it can book deliveries on your account. If your storefront needs prices, call Delivr from your own backend and pass the result on.

## Rotating and revoking

Ask Delivr for a new key, deploy it, then ask for the old one to be revoked. Both work in the meantime, so you can rotate without downtime. A revoked key answers `401 unauthenticated` straight away.

## Errors

| Status | Code                 | Meaning                                                                                           |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------- |
| 401    | `unauthenticated`    | The key is missing, unknown or revoked.                                                           |
| 403    | `insufficient_scope` | The key's scope does not cover this call.                                                         |
| 403    | `merchant_suspended` | Your merchant account is suspended. Contact Delivr.                                               |
| 429    | `rate_limited`       | Too many requests, or 30 failed sign-ins in 10 minutes from your address. Wait for `Retry-After`. |