Authentication

Basira supports two authentication methods. The web dashboard uses JWT tokens. Programmatic access (CLI, scripts, integrations) uses API keys.

API Keys

API keys are the recommended way to authenticate outside the browser. They work with all API endpoints except billing.

Format

API keys follow the format dbm_ak_<key_id>_<secret>. The full key is shown only once at creation time. After that, only the prefix (dbm_ak_<key_id>_...) is visible.

Creating Keys

1. Go to Settings > API Keys in the dashboard
2. Click Create API Key and give it a name
3. Copy the full key immediately — it cannot be retrieved later

Or via the API:

curl -X POST https://api.usebasira.com/api/v1/api-keys \
  -H "Authorization: Bearer <your-jwt-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-script"}'

Using Keys

Pass the API key in either header:

# X-API-Key header
curl https://api.usebasira.com/api/v1/databases \
  -H "X-API-Key: dbm_ak_your_key"

# Or Authorization header
curl https://api.usebasira.com/api/v1/databases \
  -H "Authorization: Bearer dbm_ak_your_key"

The agent also uses API keys — set the key in your agent config under api.key.

Revoking Keys

Delete a key from Settings > API Keys or via the API:

curl -X DELETE https://api.usebasira.com/api/v1/api-keys/{id} \
  -H "X-API-Key: dbm_ak_your_key"

Revoked keys are rejected immediately.

JWT Tokens

The web dashboard authenticates with short-lived JWT tokens stored in httpOnly cookies. You generally don't need to manage these directly, but they're available for advanced use:

• Access token — 15 minute TTL
• Refresh token — 7 day TTL
• Tokens are refreshed automatically by the dashboard

Manual Token Flow

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

# Response: { "access_token": "...", "refresh_token": "...", "expires_in": 900 }

# Use the access token
curl https://api.usebasira.com/api/v1/databases \
  -H "Authorization: Bearer <access_token>"

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

Account Verification

After signup, Basira sends a verification email. Verified accounts unlock:

• Unlimited database registrations (unverified: 1 database)
• Extended data retention (unverified: 24 hours)
• Advanced features (recommendations, remediation commands)

Resend the verification email from the dashboard banner or via:

curl -X POST https://api.usebasira.com/api/v1/auth/resend-verification \
  -H "Authorization: Bearer <access_token>"