Skip to main content
Protected API routes accept one bearer credential in the Authorization header:

​
Choose a credential

Use a PAT to create projects, inspect your memberships, or automate several projects. Use a project API key when an integration should stay isolated to one project. Missing, malformed, revoked, expired, or invalid credentials return 401 Unauthorized with an application/problem+json body. A valid credential without enough permission returns 403 Forbidden.

​
Create a personal access token

Open Account -> Security, select Create token, then choose its name, permission level, and expiry. The full bsb_pat_live_ secret is shown once. For local CLI work, browser sign-in creates and stores the PAT without requiring you to copy the secret:
For a self-hosted instance, configure both its REST API root and app origin before login. See Use the CLI with this instance. See Personal access tokens for account routes, expiry options, project selection, and token revocation.

​
Create a project API key

Open the target project, go to Settings -> API keys, and select Create key. Choose the minimum permission level the integration needs and store the full bsb_key_live_ secret when it appears. bisibility stores only a hash and cannot show the secret again. An admin PAT can also create a key for an explicit project. This is useful for automated provisioning after a user has created or obtained the initial PAT:
See API keys for listing, creation, rotation, and revocation.

​
Make a request

Set the API root and the credential you chose:
Then send it as a bearer token:
A successful request returns 200 OK with a data array and meta.next_cursor. A project API key returns its one project; a PAT returns the projects available through the user’s memberships. See List projects for the complete response shape. For a self-hosted instance, replace https://eu.bisibility.com with the app origin.

​
Permission levels

The API uses three cumulative permission levels: Both PATs and project API keys can be issued at any of these levels. Prefer the least privileged level that supports the integration. A PAT’s effective project permission is the lower of the token level and the user’s membership role in that project. For example, an admin PAT cannot exceed a viewer membership’s read access. Only a project owner can delete that project. Project API keys act with at most admin-level project permissions; only an owner’s PAT can delete a project.

​
Project selection

A project API key always belongs to one project. GET /projects returns only that project, and requests cannot use the key to access another project. A PAT follows the user’s memberships. Routes containing {project_id} select the project from the path. For routes without a project id, pass:
Selection precedence is: {project_id} path parameter, X-Bisibility-Project header, project query parameter, then inference when the PAT owner belongs to exactly one project. If the user belongs to multiple projects and no selector is present, the API returns 400 Bad Request with projectSelectionRequired.

​
Rate limits

Every request includes rate-limit headers:
Defaults: Self-hosters can change these defaults with the API rate-limit environment variables. When a limit is exceeded, the API returns 429 Too Many Requests and includes Retry-After.

​
Troubleshoot the first request

All API failures use application/problem+json; read detail before changing the request. The API error reference lists the stable codes and retry headers.