# Authentication and scopes

> Create API keys, choose what each key may do, send it with every request and stay inside the rate limit.

Source: https://docs.bakasir.com/en/docs/developers/authentication

Every request to `/v1` needs an API key. Keys belong to one business, never expire on their own and can be revoked at any time.

## Create a key

1. Open **Settings → Developer** in the Portal. Only the owner can manage keys.
2. Choose **Create key**, type a name that tells you where it is used, and pick the access for each resource.
3. Copy the key now. Bakasir stores only a hash, so it cannot be shown again. If you lose it, revoke it and create a new one.

A business can hold up to 20 active keys. Use one key per integration so you can revoke one without breaking the others.

## Send the key

Send the key as a bearer token:

```bash
curl https://api.bakasir.com/v1/me \
  -H "Authorization: Bearer bak_your_key_here"
```

The header `X-API-Key: bak_your_key_here` works too. Always call the API from your server. Never put a key in a web page or a mobile app.

## Scopes

Each key has a level per resource: no access, **read** or **write**. Write includes read.

| Resource | Levels | Used by |
| --- | --- | --- |
| `products` | read, write | `/v1/products` |
| `categories` | read, write | `/v1/categories` |
| `stock` | read, write | `/v1/stock`, `/v1/stores` |
| `customers` | read, write | `/v1/customers` |
| `sales` | read | `/v1/sales` |
| `orders` | read | `/v1/orders` |

A request outside the key's access fails with `403` and the code `insufficient_scope`.

## Rate limit

Each key may make **120 requests per minute** by default. Bakasir can raise the limit for your business. Every response carries these headers:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute |
| `X-RateLimit-Remaining` | Requests left in the current minute |
| `X-RateLimit-Reset` | Unix time when the counter resets |

When you pass the limit you get `429` with the code `rate_limited` and a `Retry-After` header in seconds. Wait that long, then continue.

## Revoke a key

Choose **Revoke** next to the key in **Settings → Developer** and hold the button. The key stops working immediately and requests with it return `401` with the code `revoked_api_key`. Revoking stays available even if the plugin lapses.

## When a key is refused

| Status | Code | Reason |
| --- | --- | --- |
| 401 | `invalid_api_key` | The key is missing, malformed or unknown |
| 401 | `revoked_api_key` | The key was revoked |
| 403 | `plugin_inactive` | The Public API plugin is not active for the business |
| 403 | `tenant_inactive` | The business account is suspended |
| 403 | `insufficient_scope` | The key has no access to this resource or method |
| 429 | `rate_limited` | Too many requests |