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

# Authentication

> Authenticate Developer API requests using the X-API-Key header.

The Developer API authenticates every request via the `X-API-Key` header.
There are no OAuth flows, bearer tokens, or session cookies on this surface.

## Creating an API key

1. Sign in to VoucherGrid.
2. Open **Settings → Account → API Keys**.
3. Click **Create key**, choose the scopes you need, and copy the full key
   value. The full key is shown **once** – store it in a secret manager
   immediately.

## Key format

API keys are issued in two formats:

| Prefix     | Mode | Use                              |
| ---------- | ---- | -------------------------------- |
| `vg_live_` | Live | Production traffic               |
| `vg_test_` | Test | Test-mode traffic and rehearsals |

The first 12 characters (the prefix) appear in the dashboard for identification – the rest of the key is never recoverable after creation.

## Sending the key

Include the key in the `X-API-Key` header on every request:

```bash theme={null}
curl -H "X-API-Key: vg_live_EXAMPLEdoNotUseThis123456" \
  https://api.vouchergrid.com/api/v1/developer/vouchers
```

```ts theme={null}
await fetch("https://api.vouchergrid.com/api/v1/developer/vouchers", {
  headers: {
    "X-API-Key": process.env.VOUCHERGRID_API_KEY!,
  },
});
```

## Authentication failures

| Status | Reason                                                           |
| ------ | ---------------------------------------------------------------- |
| 401    | `X-API-Key` header missing                                       |
| 401    | API key not recognised                                           |
| 401    | API key has been revoked                                         |
| 401    | API key has expired                                              |
| 403    | Tenant account is disabled                                       |
| 403    | Tenant subscription is not active Professional                   |
| 403    | Key is location-scoped and the request targets a different scope |
| 403    | Key is missing one of the scopes required by the endpoint        |

## Tenant scoping

Every API key belongs to exactly one tenant. All reads and writes performed via
the key are automatically scoped to that tenant – you cannot read or modify
another tenant's data, and there is no tenant ID parameter to override.

## Location-scoped keys

A key may optionally be scoped to a single location. When that is the case:

* Voucher list/get/redeem operations only see vouchers at that location.
* Voucher creation forces the new voucher to that location. Passing a different
  `location_id` in the request body returns `403 Forbidden`.