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

# Authenticate API requests

> Send a tenant API key with tenant requests, and the bootstrap token with the gateway-wide requests.

The API key belongs to a tenant and manages that tenant's apps, upstreams, and users. The bootstrap token belongs to the server and covers the few actions that no tenant owns.

| Credential | Header | Endpoints |
| - | - | - |
| API key | `Authorization: Bearer <api key>` | Every endpoint except the four in the next row. |
| Bootstrap token | `Authorization: Bootstrap <token>` | `POST /api/v1/bootstrap`, `POST /api/v1/tls/reload`, `GET /api/v1/register-bans`, and `DELETE /api/v1/register-bans/{source}`. |

An endpoint accepts only its own kind of credential.

## Use an API key

Send the key after the word `Bearer` and a space.

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" http://127.0.0.1:8080/api/v1/tenant
```

A missing or unknown API key gets `401` with `WWW-Authenticate: Bearer`. When pgw can't check the key, for example because the database doesn't answer, the request gets `500`.

`POST /api/v1/bootstrap` creates the first tenant and returns its API key in `api_key`. pgw stores only a SHA-256 hash of the key and can't show it again, so keep the key in a secret store.

## Use the bootstrap token

The bootstrap token is the value that `PGW_BOOTSTRAP_TOKEN` had when pgw started. It is at least 32 characters long. Send it after the word `Bootstrap` and a space.

```bash theme={null}
curl -s -X POST -H "Authorization: Bootstrap $PGW_BOOTSTRAP_TOKEN" http://127.0.0.1:8080/api/v1/tls/reload
```

| Situation | Status |
| - | - |
| The token is missing or wrong. | `401`, with `WWW-Authenticate: Bootstrap` |
| pgw started without `PGW_BOOTSTRAP_TOKEN`. | `403`, whatever the request sends |

To use these endpoints on a gateway that started without the token, set `PGW_BOOTSTRAP_TOKEN` and restart pgw.

## Next steps

> [card] [Handle errors](https://docs.pgw.sipmicro.services/api/errors.md)
>
> Look up what each status code means, and read the error body.

> [card] [Security](https://docs.pgw.sipmicro.services/security.md)
>
> Keep the API key, the bootstrap token, and the admin listener safe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.