# Authentication

> Create API keys, choose scopes and store restrictions, use test keys and rotate keys safely.

Source: https://shopassist.coec.dk/docs/api/authentication · Updated 2026-10-01

Send your key in the `Authorization` header:

```http
Authorization: Bearer sa_live_AbCdEfGhIjKl_0123456789abcdefghijklmnopqrstuv
```

Keys look like `sa_live_<prefix>_<secret>` or `sa_test_<prefix>_<secret>`. A missing, malformed, revoked or expired key gets `401 unauthenticated`.

## Create a key [#create]

Owners and admins create keys under **Developers → API keys** (recent sign-in and a verified email required):

1. Choose the [scopes](#scopes).
2. Optionally restrict the key to some stores. A restricted key sees only those stores everywhere, including the event log; other stores answer `404`.
3. Choose an expiry (default 1 year, at most 2 years).
4. Copy the key. It is shown once; ShopAssist stores only a hash. Owners get an email for every new key.

[Open API keys](/app/go/developers)

## Scopes [#scopes]

| Scope                 | Grants                                                           | Plan            |
| --------------------- | ---------------------------------------------------------------- | --------------- |
| `stores:read`         | list and read stores                                             | every plan      |
| `conversations:read`  | conversations, messages, handoffs, CSAT, AI content verification | API read access |
| `conversations:write` | delete conversations                                             | full API access |
| `leads:read`          | leads with consent records                                       | API read access |
| `leads:write`         | delete leads                                                     | full API access |
| `engagement:read`     | back-in-stock subscriptions                                      | API read access |
| `analytics:read`      | analytics overview and time series                               | API read access |
| `knowledge:read`      | knowledge documents                                              | API read access |
| `knowledge:write`     | upsert and delete FAQs                                           | full API access |
| `catalog:write`       | [Catalog Push API](/docs/install/generic/catalog-push-api)       | every plan      |
| `orders:report`       | order reports for attribution                                    | every plan      |
| `privacy:write`       | privacy requests                                                 | every plan      |
| `events:read`         | event log                                                        | API read access |

A request without the required scope gets `403 forbidden` with `details.required_scope`. Plan access is checked on every request: after a downgrade, keys with scopes your plan no longer includes get `403 plan_feature_unavailable` at once.

## Test keys [#test-keys]

`sa_test_…` keys are read-only development keys against your live data: they may hold only `*:read` scopes, are limited to 60 requests per minute, and write endpoints answer `403 forbidden` with `details.reason = "test_key"`.

## Rotating and revoking [#rotation]

Keys have a single secret. To rotate: create a new key, deploy it, check that **Last used** of the old key stops changing, then delete the old key. Deleting a key takes effect within 60 seconds.

> **Keep keys on the server:** Never put an API key in browser code, a mobile app or a public repository. If a key leaks, delete it immediately and
> create a new one.