Authentication
Authentication Method
GhostMind uses Bearer token authentication for the Product API:
Authorization: Bearer gmk_live_...API Key Types
| Type | Scope | Use Case |
|---|---|---|
| Human-owned | Per user | Personal API access |
| Service-owned | Per workspace | Application integration |
Scopes
Backward-compatible model: a key with no resource scopes has full data-plane access (all keys issued before scopes existed keep working). Once a key declares at least one resource scope, it is restricted to the families it names:
| Scope | Endpoint family |
|---|---|
chat | POST /v1/chat/completions |
conversations | /v1/conversations*, /v1/messages/* |
audio | /v1/audio/* |
projects | /v1/projects* |
assets | /v1/assets/* |
usage | GET /v1/usage |
actions:read | GET /v1/actions* (always requires this scope) |
actions:run | POST /v1/actions/{slug}/runs, cancellations |
admin | Bypasses all scope checks (operator keys) |
Discovery endpoints (/v1/models, /v1/capabilities, /v1/connections,
/v1/health) accept any valid key regardless of scopes.
A key without a required scope gets 403 Missing scope: <scope>.
Ask your workspace admin to grant scopes when the key is issued —
POST /admin/v1/tenants/{id}/api-keys or /me/v1/workspaces/{id}/api-keys
accept a scopes array.
Security Best Practices
- Never commit API keys to version control
- Use environment variables to inject keys
- Revoke keys when no longer needed
- Use scoped keys with minimum required permissions
- Don’t expose keys in client-side code
Next Steps
- API Keys Guide — Managing keys in the web app
- Errors — Authentication error codes