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

# Authentication

> How to issue an API key and authenticate requests against the Retailgrid Public API.

The Retailgrid Public API uses bearer tokens. Each request must include an `Authorization` header with your API key.

```http theme={null}
Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API keys are prefixed `rg_live_` and are scoped to a single Retailgrid account.

## Generate an API key

1. Sign in to [app.retailgrid.io](https://app.retailgrid.io).
2. Open **Settings → Integrations**.
3. Find the **API access** card and click **Generate API Key**.
4. Copy the key from the modal.

<Warning>
  The key is shown **only once**, at the moment of creation. Retailgrid does not store the plaintext value, so it cannot be retrieved later. Save it to your secret manager immediately.
</Warning>

Each account can have **one active key at a time**. Generating a new key replaces the previous one - existing integrations using the old key will start receiving `401 Unauthorized` and need to be updated.

## Verify a key

The fastest way to check that a key works is to call `GET /v1/auth/verify`:

```bash theme={null}
curl https://clientapi.retailgrid.io/v1/auth/verify \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

A successful response confirms the key is valid and tells you which user and key id it belongs to:

```json theme={null}
{
  "ok": true,
  "user_id": "f1c7e0b8-4a2b-4d0e-9a8b-2c3d4e5f6a7b",
  "api_key_id": "9f1c7e0b-4a2b-4d0e-9a8b-2c3d4e5f6a7b"
}
```

See the full reference on the [Verify API key](/api-reference/auth/verify) page.

## Failure modes

| Status             | Meaning                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Header missing, malformed, or the key is no longer active (rotated, revoked, or deleted). |
| `403 Forbidden`    | Key is valid but does not have access to the requested resource.                          |

## Security guidance

* **Never commit keys to source control.** Use environment variables, a secrets manager, or your CI's encrypted variables.
* **Rotate on suspicion.** Generating a new key in the UI immediately invalidates the previous one. There is no separate revoke step.
* **Use a dedicated key per integration** where possible - because each account holds one active key today, plan key rotations to align with deploys of dependent services.
* **Treat keys like passwords.** A leaked key gives full read/write access to your Retailgrid catalog and transactions.

## Need help?

If a key stops working unexpectedly or you need a key reset for an account you no longer have UI access to, contact [support](https://retailgrid.io/contact-us).