Skip to main content
Protected API routes require an API key in the Authorization header:
The router accepts a single bearer token. Missing, malformed, revoked, or invalid keys return 401 Unauthorized with an application/problem+json body.

​
Create API keys

Create the first API key from the app’s settings area. After that, an existing admin-capable key can create more keys through the REST API:
The raw token is returned only when the key is created:
Store the raw token outside bisibility. The API stores a hash and cannot show it again.

​
Scopes

The router enforces these scope classes: Current API keys authenticate with read, write, and admin. The public REST API does not currently expose a request field for limiting a new key to a subset of scopes.

​
Project scoping

An API key belongs to one project. GET /projects returns that project. Routes that include {project_id} accept either the internal project id or the public prj_... id, but the authenticated key must belong to that project.

​
Rate limits

Every request includes rate-limit headers:
Defaults: Set BISIBILITY_API_KEY_RATE_LIMIT_PER_MINUTE and BISIBILITY_PAT_RATE_LIMIT_PER_MINUTE or BISIBILITY_API_ANON_RATE_LIMIT_PER_MINUTE to change them. When a limit is exceeded, the API returns 429 and includes Retry-After.

​
Idempotency

All non-GET routes accept:
The idempotency cache key is the API key id, HTTP method, pathname, and idempotency key. Replayed responses include:
When Redis or Valkey is configured, idempotency responses are stored there with a 24-hour TTL so replays survive restarts and span app instances. The in-process Map is only a local-development and test fallback.