Authentication

Secure your API requests with API key authentication.

Overview

Raven uses API key authentication to secure all endpoints. When you register as a tenant, you receive an API key that must be included in all subsequent requests.

API Key Format

API keys follow this format:

API Key Formattext

rk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│   │    └── Random secure string
│   └── Environment (live/test)
└── Prefix (raven key)

ℹ️

Note

Only the key prefix (rk_live_xxx...) is stored for identification. The full key is hashed with SHA-256 for security.

Using API Keys

Include your API key in the Authorization header:

Authorization Headerbash

curl -X GET http://localhost:3000/api/v1/users \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx"

Getting an API Key

curl -X POST http://localhost:3000/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI App",
    "email": "dev@example.com"
  }'

Response:

Responsejson

{
  "tenant_id": "abc123-xxx-xxx",
  "api_key": "rk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "api_key_prefix": "rk_live_",
  "message": "Save your API key securely. It will not be shown again."
}

Important

Your API key is only shown once during registration. Store it securely in your environment variables or secrets manager.

API Key Scopes

API keys have scopes that control access to different resources:

Scope	Description
`memory:read`	Query and retrieve memory context
`memory:write`	Ingest and store memory
`users:read`	List and view users
`users:write`	Create and update users
`conversations:read`	List and view conversations
`conversations:write`	Create and update conversations
`tenant:read`	View tenant information
`tenant:admin`	Full tenant administration

Creating Additional Keys

Create additional API keys with specific scopes:

Create API Keybash

curl -X POST http://localhost:3000/api/v1/api-keys \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-Only Key",
    "scopes": ["memory:read", "users:read", "conversations:read"]
  }'

Error Responses

Authentication errors return the following responses:

401 Unauthorized

Missing or invalid API key

Responsejson

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

403 Forbidden

Insufficient scope for requested operation

Responsejson

{
  "error": "Forbidden",
  "message": "API key lacks required scope: memory:write"
}

Best Practices

Store API keys in environment variables, never in code

Use separate keys for different environments (dev/staging/prod)

Create keys with minimal required scopes

Rotate keys periodically and after any suspected compromise

Monitor API key usage in your tenant dashboard

Next Steps

→Tenant API →Users API →Memory API →Security Best Practices