# API authentication

> Create FeatherPanel API keys, authenticate with a Bearer token, restrict keys to IP addresses, rotate them and understand the errors the panel returns.

Source: https://featherpanel.com/docs/api/authentication/

The panel accepts two kinds of credentials on `/api` routes: the browser session cookie the frontend uses, and API
keys sent as a Bearer token. Scripts and integrations should use API keys.

## Create an API key

1. Open your **Account** page, then the **API keys** tab, and create a key.
2. Give it a name and, optionally, a list of allowed IP addresses or ranges.
3. Copy the **private key**. It is shown only once.

Each key has a public key, which identifies it, and a private key, which is the secret. Keys are tied to your user:
a request made with your key can do what you can do, including admin routes if your role has the admin permission
for them.

## Send the key

```bash
curl -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  https://panel.example.com/api/user/servers
```

The panel looks the token up as a private key first. If that fails and public-key auth is allowed, it tries it as a
public key and writes a warning to the log. Turn that fallback off with the `api_clients_allow_public_key_auth`
setting set to `false`.

## Restrict keys by IP

If a key has allowed IPs, requests from other addresses get `403 API_KEY_IP_NOT_ALLOWED`. The key's owner can be
notified when that happens (`notify_foreign_ip`). Set [`TRUST_PROXY_HEADERS`](https://featherpanel.com/docs/security#client-ips-and-proxy-trust)
correctly, or the panel may see your proxy's address instead of the client's.

## Rotate and revoke

From **Account → API keys** you can edit a key, regenerate its keys (the old private key stops working) or delete it.
Activity per key is available from `GET /api/user/api-clients/activities`. Admins can see all keys under
**Admin → API keys**.

## Errors

| HTTP | `error_code` | Meaning |
|------|--------------|---------|
| 400 | `INVALID_ACCOUNT_TOKEN` | No session and no Bearer header |
| 401 | `INVALID_API_KEY` | Token does not match any key |
| 401 | `PUBLIC_API_KEY_NOT_ALLOWED` | Public key sent while public-key auth is off |
| 403 | `API_KEY_IP_NOT_ALLOWED` | Request from an IP outside the key's allow list |
| 403 | `ACCOUNT_DELETED` | The key's user was deleted |
| 404 | `USER_NOT_FOUND` | The key's user no longer exists |
| 429 | `RATE_LIMITED` | Too many requests, see `Retry-After` |

A banned user's keys return `USER_BANNED`.

## OAuth2

Third-party apps should not ask users to paste API keys. The panel has an OAuth2 flow (authorization code and device
flow) that issues a key after the user approves a consent screen. FeatherCli's `oauth2` commands help you test it.

## Frequently asked questions

### Should I use the public key or the private key?

The private key. The panel still accepts the public key as a Bearer token for older integrations unless an admin sets api_clients_allow_public_key_auth to false, and it logs a warning each time.

### Can I see the private key again later?

No. It is shown once when you create the key. Regenerate the key if you lose it.