> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandgate.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys and scopes

> Authenticate your own integration with an API key.

Send the key as a bearer token on every request:

```http theme={null}
Authorization: Bearer bg_live_…
```

## Who can create keys

Only **company admins** can create, list and revoke keys, in **Settings → Developers** in BrandGate. A key belongs to the company, not to the person who created it, so it keeps working if that person leaves. Every create and revoke is written to an append-only audit log.

A company can have up to 25 active keys. A key works until it is revoked, so review the list now and then and revoke keys nobody uses (the list shows when each key was last used).

## Scopes

A key can only do what its scopes allow. Choose the fewest you need. A write scope never includes the matching read scope.

| Scope | Allows |
| - | - |
| `orders:read` | Read orders and their lines |
| `orders:write` | Acknowledge orders with the ERP's own order number |
| `products:read` | Read products and prices |
| `inventory:read` | Read stock levels |
| `inventory:write` | Update stock levels by SKU |
| `customers:read` | Read customers (resellers), including contact details |
| `invoices:read` | Read invoices |
| `webhooks:read` | List webhook endpoints |
| `webhooks:write` | Create and delete webhook endpoints |

A request without the right scope gets `403 insufficient_scope`, with the missing scope named in the `WWW-Authenticate` header.

## How keys are stored

BrandGate stores only a SHA-256 hash of each key. The full key is shown once when it is created and can never be shown again; if it is lost, revoke it and create a new one. In BrandGate the key is shown by its prefix and last four characters, for example `bg_live_…x9Qa`.

Keys have a recognisable prefix so secret scanners can find a leaked key. If a key leaks, revoke it in **Settings → Developers**; it stops working immediately.

## Credential prefixes

| Prefix | What it is |
| - | - |
| `bg_live_` | API key |
| `bg_at_` | OAuth access token (1 hour) |
| `bg_rt_` | OAuth refresh token (90 days, rotated on use) |
| `bg_client_` | OAuth client id |
| `bg_cs_` | OAuth client secret |
| `whsec_` | Webhook signing secret |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.