API Authentication

clariBI supports two authentication methods: JWT tokens for interactive sessions and API keys for server-to-server integrations. Choose the method that fits your use case.

JWT Token Authentication

JWT (JSON Web Token) is the primary auth method, used by the clariBI web app and ideal for user-facing integrations.

Obtaining a Token

POST /api/auth/login/
Content-Type: application/json

{
  "email": "user@company.com",
  "password": "your-password"
}

Response:

{
  "access": "eyJ0eXAiOiJKV1Qi...",
  "refresh": "eyJ0eXAiOiJKV1Qi...",
  "user": {
    "id": 1,
    "email": "user@company.com",
    "organization": "Acme Corp"
  }
}

Using the Token

Include the access token in the Authorization header:

GET /api/reports/
Authorization: Bearer eyJ0eXAiOiJKV1Qi...

Token Expiry and Refresh

Access tokens expire after 1 hour. When expired, use the refresh token:

POST /api/auth/token/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1Qi..."
}

Refresh tokens are valid for 7 days. After that, the user must log in again.

API Key Authentication

API keys are better for automated scripts, CI/CD pipelines, and server-to-server communication.

Creating an API Key

1. Go to Settings > Developer > API Keys
2. Click Generate New Key
3. Enter a name and optional description (e.g., "Production ETL Pipeline")
4. Choose an expiry: 30 days, 90 days, 1 year, or never expires
5. Copy the key immediately — it is shown only once

Using an API Key

GET /api/reports/
X-API-Key: claribi_key_abc123def456...

Key Permissions

API keys inherit the organization role of the user who created them. A Viewer's API key cannot perform Admin actions. The key has the same access as the user who created it.

Security Best Practices

• Store API keys in environment variables, never in code
• Set an expiry date on keys when possible
• Rotate keys periodically (every 90 days recommended)
• Revoke unused keys promptly
• Use JWT tokens for user-facing apps, API keys for automated systems

MFA and API Authentication

API keys bypass MFA by design — they are intended for automated systems. JWT login for accounts with MFA enabled requires the TOTP code as an additional field in the login request.

Related

• API Reference Overview
• MFA Setup
• Roles & Permissions