Authentication: JWT Tokens vs. API Keys

Overview

The clariBI API supports two authentication methods: JWT (JSON Web Tokens) and API keys. Both grant access to the same endpoints and data, but they differ in how they are issued, how long they last, and where they are best used.

This guide compares the two methods in detail so you can choose the right one for your integration.

How JWT Authentication Works

The Token Flow

1. Your application sends the user's email and password to /api/auth/login/.
2. clariBI verifies the credentials and returns two tokens:
3. Access token -- Short-lived (1 hour), used for API requests.
4. Refresh token -- Longer-lived (7 days), used to get a new access token.
5. Your application includes the access token in the Authorization header of each request.
6. When the access token expires, your application sends the refresh token to /api/auth/token/refresh/ to get a new access token.
7. When the refresh token expires, the user must log in again.

Token Lifecycle

Login → Access Token (1hr) + Refresh Token (7d)
         ↓ (expired)
         Refresh → New Access Token (1hr)
         ↓ (refresh expired)
         Login again

JWT Request Example

# Login
curl -X POST https://claribi.com/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

# Use the access token
curl -H "Authorization: Bearer eyJ0eXAi..." \
  https://claribi.com/api/dashboards/

# Refresh when expired
curl -X POST https://claribi.com/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAi..."}'

JWT Security Properties

• Short-lived: Access tokens expire in 1 hour, limiting the window if a token is intercepted.
• User-scoped: Each token is tied to a specific user and their permissions.
• Stateless: The server does not store tokens. Validation is done by verifying the token's signature.
• MFA-compatible: If MFA is enabled, the login flow requires a TOTP code before issuing tokens.

How API Key Authentication Works

The Key Flow

1. A user creates an API key in the clariBI web interface (Settings > Security > API Keys).
2. The key is displayed once and must be copied immediately.
3. Your application includes the key in the X-API-Key header of each request.
4. The key remains valid until it expires or is revoked.

API Key Request Example

curl -H "X-API-Key: claribi_sk_live_abc123xyz..." \
  https://claribi.com/api/reports/

API Key Security Properties

• Long-lived: Keys do not expire on a timer unless an expiration date is set during creation.
• User-tied: Each key inherits the permissions of the user who created it.
• Scopeable: Keys can be scoped to read-only or read-write access.
• Revocable: Keys can be revoked instantly from the web interface.
• No MFA bypass: API keys are created after the user has already authenticated (including MFA if enabled), so they do not bypass MFA.

Comparison Table

When to Use JWT

User-facing web or mobile applications where a real user logs in and interacts with clariBI through your app. JWT is ideal when:

• The user's session is interactive and short-lived
• You want automatic session expiration for security
• MFA enforcement on each login is important
• You need a higher rate limit (1,000 requests/minute)

Implementation Pattern

import requests

# Login
response = requests.post('https://claribi.com/api/auth/login/', json={
    'email': 'user@example.com',
    'password': 'password123'
})
tokens = response.json()
access_token = tokens['access']
refresh_token = tokens['refresh']

# Make requests
headers = {'Authorization': f'Bearer {access_token}'}
dashboards = requests.get('https://claribi.com/api/dashboards/', headers=headers)

# Refresh when needed
response = requests.post('https://claribi.com/api/auth/token/refresh/', json={
    'refresh': refresh_token
})
new_access = response.json()['access']

When to Use API Keys

Server-side automation, scripts, and third-party integrations where no interactive user is present. API keys are ideal when:

• A script runs on a schedule (daily data export, weekly report)
• A third-party service needs persistent access
• You want simple, single-header authentication
• The integration runs unattended

Implementation Pattern

import requests

API_KEY = 'claribi_sk_live_abc123xyz...'  # From environment variable

headers = {'X-API-Key': API_KEY}
reports = requests.get('https://claribi.com/api/reports/', headers=headers)

Security Best Practices

For JWT

• Store tokens securely. In web apps, store the access token in memory (not localStorage). Store the refresh token in an HttpOnly cookie.
• Handle expiration gracefully. Implement automatic refresh logic so users are not interrupted by token expiry.
• Clear tokens on logout. Remove both tokens from the client when the user logs out.

For API Keys

• Never hardcode keys. Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).
• Rotate every 90 days. See API Keys: Create, Scope, Rotate, Revoke.
• Use the minimum scope. If a script only reads data, create a read-only key.
• One key per integration. Separate keys for each use case so you can revoke independently.
• Monitor usage. Check the API key activity log in clariBI for unexpected patterns.

For Both

• Always use HTTPS. The API rejects HTTP requests, but ensure your client code does not accidentally downgrade.
• Handle 401 errors. Implement retry logic with fresh authentication when you receive a 401 response.
• Respect rate limits. Check the Retry-After header on 429 responses and back off accordingly.

Combining Both Methods

Some architectures use both:

• JWT for the frontend -- Your web app authenticates users with JWT, providing a responsive, session-based experience.
• API key for the backend -- Your server uses an API key for background jobs like data syncing, report generation, or webhook handling.

This separation keeps user-facing traffic on the higher-rate-limit JWT path and background automation on dedicated API keys.

Related Articles

• API Quick Start: Base URL, Auth, First Request
• API Keys: Create, Scope, Rotate, Revoke
• Endpoint Reference: Data Sources, Reports, Dashboards
• MFA Setup: TOTP Authenticator App and Backup Codes