Authentication

Most API endpoints are prefixed with https://api.dbtrail.com/api/v1/. The Claude integration endpoint is at /mcp (no version prefix). Authentication is required for all endpoints.

dbtrail supports two authentication methods: JWT tokens for browser sessions and API keys for programmatic access.

JWT authentication

JWTs are short-lived tokens issued by Supabase GoTrue after an OAuth or email/password login. They are used by the dashboard (React frontend) and are not typically used directly by API consumers.

Headers required

Authorization: Bearer <jwt_token>
X-Tenant-ID: <tenant_uuid>

The X-Tenant-ID header is required because a user can belong to multiple tenants. If the user belongs to only one tenant, the header can be omitted and the tenant is resolved automatically.

API key authentication

API keys are long-lived, static tokens for machine-to-machine scenarios: AI assistants (Claude, Cursor), scripts, CI/CD pipelines, and the dbtrail agent.

Headers required

Authorization: Bearer bt_live_<32_hex_chars>

Key format

bt_live_<32 random hex characters>

Example: bt_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Validation flow

For API keys, the validation process is:

1. Format check — reject if key doesn't match bt_(live|test)_[0-9a-f]{32}
2. Hash and lookup — SHA-256 hash the key, query the api_key_lookup table
3. Revocation check — verify the key hasn't been revoked
4. Expiry check — check expires_at against current UTC time
5. Return context — user ID, tenant ID, tenant slug, role, and plan

Comparison

Rate limiting

Both authentication methods are subject to rate limiting based on the tenant's plan. Limits are enforced per-user and per-tenant independently: