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.
On this page
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
- Open your Account page, then the API keys tab, and create a key.
- Give it a name and, optionally, a list of allowed IP addresses or ranges.
- 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
curl -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
https://panel.example.com/api/user/serversThe 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
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
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.
No. It is shown once when you create the key. Regenerate the key if you lose it.