# Authentication

Every request carries a secret key in the `Authorization` header:

```http
Authorization: Bearer nz_live_sk_...
```

## Keys

- **Who makes them:** a store's owners and admins, in **Settings → Developers**.
- **What a key belongs to:** one store, not a person. It keeps working when the person who made it leaves.
- **Shown once:** only a fingerprint is kept. If a key is lost, roll it to get a new one.
- **Easy to spot:** keys start with `nz_live_sk_` and end with a checksum, so secret scanners can recognise a leaked key.
- **Server only:** a request carrying a key from a browser (one with an `Origin` header) is refused with `browser_request_refused`. Never put a key in a website, a mobile app or a public repository.

### Rolling and revoking

- **Roll** a key to replace it. You get a new key with the same permissions, and the old one keeps working for **24 hours**, so you can switch over without downtime.
- **Revoke** a key to stop it at once, for example if it was leaked.

A revoked, expired or unknown key, or a key of a suspended account, gets `401 invalid_api_key`. The answer is the same in every case, on purpose.

## Permissions (scopes)

Choose only what the system needs. Changing something includes seeing it.

| Scope             | Allows                                              |
| ----------------- | --------------------------------------------------- |
| `read_products`   | See products and variants                           |
| `write_products`  | Create and change products and variants             |
| `read_inventory`  | See stock levels                                    |
| `write_inventory` | Adjust and set stock                                |
| `read_orders`     | See orders, including shoppers' names and addresses |
| `write_orders`    | Cancel orders                                       |
| `read_customers`  | See customers' names, emails and phone numbers      |
| `read_costs`      | See product costs; also needed to set a cost        |

A request needing a scope the key lacks gets `403 insufficient_scope`, and the message names the scope. Permissions can be changed in **Settings → Developers** at any time, without a new key.

`GET /v1/store` needs no scope: use it to check a key works.

## Shoppers' data

Orders and customers carry personal details. How many orders and customers each key reads per day is shown to the store's owners and admins on **Settings → Data exports**. Read only what you need, and keep it as safe as the store would.