# Authentication and keys

Send your key in the `Authorization` header of every request:

```
Authorization: Bearer pbn_1a2b3c4d5e6f_Xy...
```

`X-API-Key: pbn_...` works too. Keys are never accepted in the URL (they would end up in logs).

## Creating keys

Open [API keys](/api/keys/) and click **Create key**. You choose:

- **Name** - what the key is for ("Grafana dashboard", "Deploy script").
- **Access** - *Full access* (everything your account can do) or *Scoped*: only the permissions you tick
  (see [Scopes](/api/docs/scopes)). Give each tool only what it needs.
- **Sites** - all sites, or only the sites you pick. A restricted key cannot see or touch any other site and cannot
  create sites.
- **Expiry** - never, or after a number of days / on a date.
- **IP allowlist** - optional: one IP address or range (CIDR) per line; calls from anywhere else get
  `403 ip_not_allowed`.

The full key is shown **once**. We store only a hash of it: if you lose it, revoke it and make a new one. You can have
many keys; each shows when and from which IP it was last used. **Revoke** stops a key at once; revoked keys move to a
hidden list at the bottom of the page.

## Key format

`pbn_<12 characters>_<secret>`. The first part (`pbn_1a2b3c4d5e6f`) is the key's public prefix, shown on the keys page
and in the call log; the secret after it is never shown again.

## OAuth (apps and AI assistants)

Apps such as AI assistants connect with OAuth 2.1 instead of a pasted key: you log in to PBN.LTD, see what the app
asks for, and approve. Discovery: `https://app.pbn.ltd/.well-known/oauth-authorization-server`. Dynamic client
registration, authorization code with PKCE (S256) and refresh-token rotation are supported. Connected apps are listed
on the [API keys](/api/keys/) page, where you can disconnect them. See [MCP](/api/docs/mcp).

## Security tips

- Never put a key in client-side code of a public web page or in a git repository.
- Use a scoped key, restricted to the sites it needs, with an IP allowlist for servers with fixed addresses.
- Rotate keys: create the new key, switch your tool, then revoke the old one.