# Authentication

Every request sends an API key in the `api_key` query parameter:

```bash
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY"
```

## Two kinds of API key

| | Shop API key | Account API key |
|---|---|---|
| Created in | **Settings › Apps › Webhook/API**, **API Key** tab | **Account › API Key** |
| Works for | One shop | Every shop the account belongs to |
| Permissions | Full Open API access to the shop | The account's own permissions in each shop: role, warehouses, department, work hours, allowed IPs |
| Key format | Random string | Starts with `pos_user_` |
| Best for | Background integrations between two systems (ERP, website) | Tools acting on behalf of one person: personal scripts, [MCP](/developers/mcp/en) |

Both kinds call the same endpoints. An account key is rejected (`403`) for actions the account is not allowed to do.

## Shop API key

1. Open **Settings › Apps** and choose **Webhook/API**.
2. Open the **API Key** tab and click **Add**. Note what the key is for so it is easy to manage.
3. Copy the key and store it somewhere safe on your server.

Delete a key in the same list when you no longer need it; systems using it are rejected immediately.

## Account API key

1. Open the **Account** page, **API Key** section, and click **Create**.
2. Name it after its purpose (for example "Claude" or "Daily report").
3. The key is shown **only once** after creation: copy it right away.

One key works for every shop you belong to:

- Call `GET /shops` to see which shops the key can access; every other endpoint needs `{SHOP_ID}` in the path.
- Leaving a shop or having your permissions changed takes effect on the key immediately.
- Rename or revoke the key in the same list. An API key cannot create or revoke other API keys.

## Keep keys safe

- An API key is as powerful as a password: never ship it in browser or mobile app code, never commit it to git, never send it in chat.
- Call the Open API from your server and read the key from an environment variable or a secret store.
- If a key may have leaked, delete or revoke it at once and create a new one.
- 20 wrong `api_key` attempts within a minute from the same IP address lock that address for 5 minutes (`429`, code `109`, with a `Retry-After` header).

## In POS Apps

Apps running inside POS do not use API keys: POS issues an app token for the person using the app. See [POS Apps › Data access](/developers/apps/en/data-access).