Authentication: JWT tokens, API keys and MCP keys

Three kinds of credentials

For scripts and integrations, use an API key with the REST API v1. It is documented at https://claribi.com/api/v1/docs/ and in the API authentication page of the documentation, scoped and meant for outside use. The JWT-based /api/ endpoints serve the web app and can change without notice.

API keys (REST API v1)

1. Create a key in Settings > Developer > API Keys and choose its scopes and expiry.
2. Send it as a bearer token:

curl -H "Authorization: Bearer $CLARIBI_API_KEY" \
  https://claribi.com/api/v1/dashboards/

Properties:

• Lifetime: until the expiry you chose (30 days, 90 days, 1 year) or until you revoke it.
• Scopes: each key only does what its scopes allow, such as reports:read or dashboards:refresh.
• Organization-bound: the key works for the organization it was created in, and only while that organization is on Professional or Enterprise.
• No password or MFA at use time: keys are created by a signed-in user, so store them like passwords.
• Stored as a hash: clariBI cannot show a key again after creation.

See API keys.

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['CLARIBI_API_KEY']}"}
resp = requests.get("https://claribi.com/api/v1/reports/", headers=headers, timeout=30)
resp.raise_for_status()
for report in resp.json()["results"]:
    print(report["id"], report.get("title"))

JWT tokens (the web app's API)

This is how the clariBI web app signs you in:

1. POST /api/auth/login/ with email and password returns your user and a pair of tokens:

{
  "user": {"id": "...", "email": "you@example.com"},
  "tokens": {"access": "eyJ...", "refresh": "eyJ..."}
}

1. If two-factor authentication is on, the login answers that MFA is required instead, and the six-digit code has to be verified before tokens are issued.
2. The access token lasts 60 minutes and goes in Authorization: Bearer <access token>.
3. The refresh token lasts 7 days. POST /api/auth/token/refresh/ with {"refresh": "..."} returns a new access token and a new refresh token; the old refresh token stops working.
4. Signing out invalidates the session.

Use JWT only if you are building something that acts on behalf of a signed-in person and you accept that these endpoints may change.

MCP keys and OAuth (MCP server)

The clariBI MCP server lets AI clients such as Claude, Cursor or ChatGPT work with your clariBI data through 26 tools (list dashboards, run analyses, generate reports and more). Clients connect with OAuth 2.1, or with an MCP key that starts with claribi_mcp_. Set it up in Settings > Developer under MCP Server. MCP keys do not work with the REST API, and REST API keys do not work with the MCP server. The MCP authentication page in the documentation covers both methods, and OAuth 2.1 with DCR explained explains the OAuth flow.

Comparison

Security practice

• Keep keys and tokens on the server. Never ship them in browser or mobile code.
• Use environment variables or a secrets manager, never source control.
• Give each integration its own key with minimal scopes, so you can revoke one without breaking others.
• Handle 401: for API keys, check expiry and revocation; for JWT, refresh the token and retry once.
• Respect 429: wait until the time in X-RateLimit-Reset.

Related articles

• API quick start
• API keys
• Endpoint reference
• Two-factor authentication