Send a key
Send the key as a bearer token on every call. Keys start with pbk_.
curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "https://dashboard.perfbee.com/api/v1/me"
Nothing else is accepted. These all answer invalid_key: a key in the address, a cookie, a dashboard sign-in token, an X-API-Key header, and an OAuth token that starts with pbo_ (those belong to the MCP connection). The answer carries WWW-Authenticate: Bearer realm="perfbee-api".
The message never says why a key failed: it may be wrong, revoked, expired, or its owner may have left the workspace. Check the key in Settings > API keys.
Make a key
- In the dashboard open Settings > API keys.
- Give the key a name, such as the system it runs in. Choose its access: Read only or Read and start crawls. Tick Also manage webhooks if the key will manage webhook endpoints.
- Choose when it expires: never, or after 30, 90 or 365 days. A key made for a script that runs for a while should expire, so a forgotten key stops working.
- Copy the key. It is shown once. PerfBee keeps only a hash of it.
A workspace can have 5 active keys. Viewers cannot make keys. A key acts for the workspace and uses its credits.
Scopes
| Scope | Allows | Includes |
|---|---|---|
| read | Read sites, crawls, issues, pages, fixes and the issue catalog. Free of credits. | only itself |
| crawl | Start and cancel crawls. Crawls spend credits. | read |
| webhooks | Create, change and delete webhook endpoints, and read their deliveries. | only itself |
A call to an endpoint the key has no scope for answers scope_required, and required_scope names the scope. Every endpoint in the reference says which scope it needs.
A key acts with the role of the person who made it, checked on every call. If that person becomes a viewer, their keys can only read from then on. If they leave the workspace, their keys stop working.
The daily credit cap
A key that can start crawls carries a daily credit cap: the most its crawls may cost in one day, counted at their worst case when they start. The day ends at UTC midnight. The default is 2,000 credits. You can set any cap up to 1,000,000, or choose no cap.
When a crawl would pass the cap, the call answers daily_credit_cap_reached with Retry-After set to the seconds until the day ends. Keep a cap on every key that lives in CI or in any place it could leak.
Keys made before the REST API have no cap set. A crawl started with such a key may check 500 pages at most. A key with a cap, or one made with no cap, may ask for up to 10,000 pages.
Keep a key safe
- Keep it in an environment variable or a secret store. Never in a file you commit, and never in code that runs in a browser.
- The API sends no cross-origin headers, so a browser page cannot call it. Call it from a server or a build job.
- Revoking a key in Settings > API keys stops it at once. So does removing the person who made it from the workspace.
- PerfBee stores a hash of each key, never the key. The time a key was last used is stored, at most once a minute. Details are in the Privacy Policy.