Role-Based Access Control

Chat-in-Bio uses API keys with assigned roles to control access to the Admin API.

Roles

Role	Read	Create	Update	Delete	Manage keys
admin	Yes	Yes	Yes	Yes	Yes
editor	Yes	Yes	Yes	No	No
viewer	Yes	No	No	No	No

How it works

Environment key (backwards compatible)

The CHATINBIO_ADMIN_API_KEY environment variable always grants admin role. This is the default single-tenant setup.

Database keys

Additional keys can be created via the Admin API or CLI. These are stored hashed (SHA-256) in the api_keys table and support role assignment.

# Create an editor key
chtbio keys create --role editor --label "CI pipeline"
# Output: chtbio_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Save this key — it cannot be retrieved again.

# Create a viewer key for monitoring
chtbio keys create --role viewer --label "Dashboard"

Authentication flow

1. Client sends Authorization: Bearer <key> header
2. Server checks against env var first (admin role if match)
3. If no match, hashes the key and checks the api_keys table
4. If found and active, the key's role is applied
5. Each endpoint enforces role requirements:
   • GET endpoints: any role
   • POST/PUT endpoints: admin or editor
   • DELETE endpoints: admin only
   • Key management (/api/admin/keys): admin only

Managing keys

List keys

chtbio keys list

Shows key prefix, label, role, and status. The full key is never shown after creation.

Create a key

chtbio keys create --role editor --label "Description"

The full key is shown once. Store it securely.

Revoke a key

chtbio keys revoke KEY_ID

Revoked keys are deactivated (soft delete), not removed from the database.

Recommended setup

Use case	Role	Notes
Admin/owner	admin (env key)	Full access, used for initial setup
CI/CD pipeline	editor	Can deploy content, cannot delete or manage keys
AI agent	editor	Combined with CLI policy restrictions
Monitoring dashboard	viewer	Read-only access to content