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

# Authentication

> API keys, required headers and scopes

Every endpoint requires an API key, sent as a bearer token.

```bash theme={null}
curl "https://api.komerza.com/stores/{storeId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"
```

## Creating a key

1. Open **[Account Settings → API Keys](https://dashboard.komerza.com/account?api)** in the dashboard
2. Click **Create New API Key** and name it after the integration that will use it
3. Select its scopes
4. Copy the key

<Warning>
  The key is shown once and can't be retrieved later. Keep it in an environment
  variable or a secrets manager, never in source control.
</Warning>

## Required headers

| Header          | Required  | Value                                            |
| --------------- | --------- | ------------------------------------------------ |
| `Authorization` | Yes       | `Bearer YOUR_API_KEY`                            |
| `User-Agent`    | Yes       | Something identifying your app, e.g. `MyApp/1.0` |
| `Content-Type`  | On writes | `application/json`                               |

## Scopes

Each key carries a fixed set of scopes, chosen when you create it. They decide which endpoints it can reach: `stores.orders.view` to read orders, `stores.orders.refund` to refund them, and so on.

Scopes can't be edited afterwards. To change what a key can do, create a new one and retire the old.

Two habits worth adopting from the start:

* **One key per integration.** You can then revoke a single integration without breaking everything else.
* **Only the scopes it needs.** A reporting script has no business holding `stores.orders.refund`.

<Card title="All scopes" icon={<span className="kicon kicon-shield" />} href="/api-reference/scopes">
  Every permission a key can carry, and what each one unlocks.
</Card>

## When authentication fails

| Status | Meaning                           | Fix                                                                                                  |
| ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `401`  | Key missing, malformed or revoked | Check the `Bearer ` prefix is present and the key still exists                                       |
| `403`  | Key is valid but lacks the scope  | Scopes follow the resource, e.g. orders need `stores.orders.*`. Create a new key with the right ones |

Both return the standard error envelope, with `code` set to `AccessDenied`. See [Responses & Errors](/api-reference/responses).