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
- Open Settings > Developer. Only Owners and Administrators can create keys.
- In API Keys, click Generate New Key.
- Enter a name (for example "Nightly ETL") and, if you like, a description.
- Tick the scopes the integration needs. At least one is required.
- Choose an expiry: 30 days, 90 days, 1 year or never.
- Copy the key. It is shown once; clariBI stores only a hash of it.
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.
| Scope | Allows |
|---|---|
reports:read | List, read and download reports |
reports:generate | Generate reports (uses AI credits) |
reports:delete | Delete reports |
reports:share | Turn report public links on and off |
dashboards:read | List and read dashboards |
dashboards:create | Create dashboards |
dashboards:update | Edit dashboards |
dashboards:delete | Delete dashboards |
dashboards:refresh | Refresh dashboards (uses AI credits) |
dashboards:share | Turn dashboard public links on and off |
data_sources:read | List and read data sources, start a sync |
goals:read | List goals and read progress |
usage:read | Read usage counters |
forecasts:read | List forecasts, read runs and accuracy, estimate cost |
forecasts:write | Create, change and delete forecasts |
forecasts:run | Run 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.