dbtrail Documentation

API keys provide long-lived authentication for programmatic access to dbtrail. They are the recommended authentication method for AI assistants (Claude, Cursor), scripts, and CI/CD pipelines.

Generating a key

Go to Dashboard → Settings → API Keys
Click Generate New Key
Re-authenticate with your password
Name the key (e.g., "Claude Desktop", "CI/CD Pipeline")
Select scopes: all / query-only / status-only
Set expiry: never / 30 days / 90 days / 1 year
Copy the key — it is shown only once

Save your key

The full API key is displayed exactly once at creation time. After that, only the prefix (e.g., bt_live_a1b) is shown. If you lose the key, you must generate a new one.

Key properties

Each API key is:

Tied to a user and tenant — inherits the user's role within that tenant
Scoped — can be restricted to specific operations (e.g., query and status only)
Expirable — optional expiry date
Revocable — can be revoked instantly from the dashboard
Audited — every use is logged with the key ID

Using a key

Include the key in the Authorization header:

curl https://api.dbtrail.com/api/v1/servers \
  -H "Authorization: Bearer bt_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

No tenant header needed

Unlike JWT authentication, API keys automatically resolve the tenant. The X-Tenant-ID header is not required.

Security

API keys are never stored in plaintext — only the SHA-256 hash is persisted
The key prefix (bt_live_a1b) is stored separately for display in the dashboard
If the database is compromised, attackers get hashes — not usable tokens
Key validation uses an O(1) lookup table indexed by hash

Revoking a key

Go to Dashboard → Settings → API Keys and click Revoke next to the key. Revocation is immediate — any in-flight requests using the key will fail.

Availability

API keys are available on all plans, including Free. This is by design — dbtrail uses limits (not features) as the gating mechanism, so Claude and API access are never locked behind a paywall.