API authentication

Last reviewed against the app on 24 September 2026

The REST API at /api/v1/ accepts one kind of credential: an API key that starts with claribi_, sent as a Bearer token. Keys are available on the Professional and Enterprise plans.

Create a key

  1. Open Settings > Developer. Only Owners and Administrators can create keys.
  2. In API Keys, click Generate New Key.
  3. Enter a name (for example "Nightly ETL") and, if you like, a description.
  4. Tick the scopes the integration needs. At least one is required.
  5. Choose an expiry: 30 days, 90 days, 1 year or never.
  6. Copy the key. It is shown once; clariBI stores only a hash of it.
Settings, Developer tab with the API Keys section

Use the key

curl https://claribi.com/api/v1/auth/verify/ \
  -H "Authorization: Bearer claribi_xxxxxxxxxxxxxxxx"

auth/verify/ returns the key's name, scopes and expiry plus the organization and plan, which makes it a good first call.

The key acts for the organization it was created in. Requests stop working, with HTTP 401, when:

  • the key is deleted or has expired;
  • the person who created it is deactivated or removed from the organization;
  • the organization moves to a plan without API access, or its subscription is suspended or cancelled.

MCP keys (claribi_mcp_...) are rejected by the REST API; they work only with the MCP server. The session tokens the web app uses are not accepted on /api/v1/ either.

Scopes

A key can call only the endpoints its scopes allow. A missing scope returns HTTP 403.

ScopeAllows
reports:readList, read and download reports
reports:generateGenerate reports (uses AI credits)
reports:deleteDelete reports
reports:shareTurn report public links on and off
dashboards:readList and read dashboards
dashboards:createCreate dashboards
dashboards:updateEdit dashboards
dashboards:deleteDelete dashboards
dashboards:refreshRefresh dashboards (uses AI credits)
dashboards:shareTurn dashboard public links on and off
data_sources:readList and read data sources, start a sync
goals:readList goals and read progress
usage:readRead usage counters
forecasts:readList forecasts, read runs and accuracy, estimate cost
forecasts:writeCreate, change and delete forecasts
forecasts:runRun forecasts and rewrite their summaries (uses AI credits)

auth/verify/ works with any valid key. Pick the smallest set of scopes that does the job: a job that only reads dashboards needs dashboards:read and nothing else.

Manage and revoke keys

In Settings > Developer > API Keys, each key shows its status and when it was created. Use the key's menu to Rename or Delete it. A deleted key stops working on the next request. Creating a key is recorded in the audit log.

Good practice

  • Keep keys in environment variables or a secrets store, not in code.
  • Give each integration its own key, so you can delete one without breaking the others.
  • Set an expiry where you can, and replace keys regularly.
  • Delete a key at once if it may have leaked.

Keys and MFA

API keys are meant for unattended systems and are not tied to a sign-in, so multi-factor authentication does not apply to them. Protect them like passwords.

Related

Try it on your own data

The 14-day trial includes 50 AI credits and needs no card. When it ends you move to the Free plan and keep your data.