API Tokens

API tokens authenticate the Babelon CLI (and any other programmatic access) with your Babelon backend. They consist of two parts: a client ID and a secret token.

How API tokens work

Instead of using your personal login credentials, the CLI sends an API token pair with every request:

• Client ID (X-Client-Id header) -- Identifies which token is being used.
• Secret token (X-Api-Token header) -- Proves you have authorization.

The server looks up the client ID, verifies the token against a stored SHA-256 hash, and resolves your organization from the token's database record. This means the token itself determines which organization you are accessing -- it cannot be used to access a different organization.

Generating a token

You need admin or owner permissions to generate API tokens.

1. Go to Settings in the sidebar.
2. Scroll to the API Access section.
3. Click Generate Token.
4. Give it a descriptive name (e.g., "CI/CD Pipeline" or "Local Development").
5. The token pair is displayed in a modal.

Important

The secret token is shown only once. Copy both the client ID and the token immediately. After you close the modal, the secret token cannot be retrieved -- only a hash is stored on the server.

Token format

Part	Prefix	Example
Client ID	bbl_cid_	bbl_cid_a1b2c3d4e5f6g7h8
Secret token	bbl_tok_	bbl_tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The client ID contains 16 hex characters after the prefix. The secret token contains 32 hex characters after the prefix.

Configuring the CLI

Add your token to .babelon.toml:

supabase_url = "https://your-project.supabase.co"
client_id    = "bbl_cid_a1b2c3d4e5f6g7h8"
api_token    = "bbl_tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
tenant_id    = "your-tenant-uuid"

Or use environment variables:

export BABELON_CLIENT_ID="bbl_cid_a1b2c3d4e5f6g7h8"
export BABELON_API_TOKEN="bbl_tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

TIP

For CI/CD pipelines, use environment variables or secrets management rather than committing tokens to your repository. Add .babelon.toml to your .gitignore if it contains a token.

Managing tokens

Viewing tokens

The API Access section in Settings shows all tokens for your organization:

• Token name
• Client ID (always visible)
• When it was created
• When it was last used

The secret token is never shown after initial generation.

Revoking tokens

To revoke a token:

1. Go to Settings > API Access.
2. Find the token in the list.
3. Click Revoke.

Revoked tokens stop working immediately. Any CLI or automation using that token will receive authentication errors. You can generate a new token to replace a revoked one.

Security details

• Hashed storage -- Only the SHA-256 hash of the secret token is stored in the database. The raw token is never persisted.
• Tenant binding -- Each token is bound to a specific organization. The server always reads the tenant ID from the database record, preventing any attempt to access a different organization.
• Usage tracking -- The last_used_at timestamp is updated on every authenticated request, so you can see which tokens are actively in use.
• Revocable -- Tokens can be revoked instantly from the Settings page. Revocation is permanent.
• Role-scoped generation -- Only admins and owners can create or revoke tokens. Members and viewers can see the token list but cannot manage tokens.