Ravenraven

Tenants API

Register and manage your tenant account.

Overview

A tenant represents a developer or organization integrating with Raven. Each tenant has isolated storage, their own API keys, and can manage multiple users and conversations.

Endpoints

POST/api/v1/tenantsPublic

Register a new tenant (returns API key)

No auth required
GET/api/v1/tenant

Get current tenant information

tenant:read
PATCH/api/v1/tenant

Update tenant settings

tenant:admin
POST/api/v1/api-keys

Create additional API key

tenant:admin

Register Tenant

Register a new tenant account. This is the only public endpoint - no authentication required.

Request

POST /api/v1/tenantsbash
curl -X POST http://localhost:3000/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Company",
    "email": "developer@example.com",
    "settings": {
      "retention_days": 90,
      "max_conversations_per_user": 50
    }
  }'

Parameters

FieldTypeRequiredDescription
namestringYesYour organization name
emailstringYesContact email (must be unique)
settingsobjectNoInitial configuration

Response

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

Critical

The API key is only returned once during registration. Store it immediately in a secure location like a secrets manager or environment variables.

Get Tenant Info

Retrieve your tenant information and current settings.

GET /api/v1/tenantbash
curl -X GET http://localhost:3000/api/v1/tenant \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx"
Response (200 OK)json
{
  "tenant_id": "abc123-xxx-xxx-xxx",
  "name": "My AI Company",
  "email": "developer@example.com",
  "settings": {
    "retention_days": 90,
    "batch_size": 10,
    "max_conversations_per_user": 50,
    "max_users": 1000,
    "encryption_mode": "platform"
  },
  "stats": {
    "user_count": 150,
    "conversation_count": 1250,
    "total_interactions": 45000,
    "storage_bytes": 52428800
  },
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update Tenant

Update your tenant settings. Requires tenant:admin scope.

PATCH /api/v1/tenantbash
curl -X PATCH http://localhost:3000/api/v1/tenant \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Company Inc.",
    "settings": {
      "retention_days": 180,
      "max_conversations_per_user": 100,
      "webhook_url": "https://api.example.com/webhook",
      "webhook_events": ["memory.ingested", "conversation.created"]
    }
  }'

Tenant Settings

SettingTypeDefaultDescription
retention_daysnumber30Days to retain memory blobs
batch_sizenumber10Interactions before flush
max_conversations_per_usernumber100Max conversations per user
max_usersnumber1000Max users for tenant
encryption_modestringplatformEncryption key management mode
webhook_urlstring-URL for event webhooks
webhook_eventsstring[]-Events to send to webhook

Create API Key

Create additional API keys with specific scopes.

POST /api/v1/api-keysbash
curl -X POST http://localhost:3000/api/v1/api-keys \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Read-Only",
    "scopes": ["memory:read", "users:read", "conversations:read"]
  }'
Response (201 Created)json
{
  "key_id": "key_xxxxxxxxx",
  "api_key": "rk_live_yyyyyyyyyyyyyyyyyyyy",
  "api_key_prefix": "rk_live_yy",
  "name": "Production Read-Only",
  "scopes": ["memory:read", "users:read", "conversations:read"],
  "created_at": "2024-01-15T10:30:00Z",
  "message": "Save your API key securely. It will not be shown again."
}

Tenant Object

Tenant Schematypescript
interface Tenant {
  id: string;                // Unique tenant ID
  name: string;              // Organization name
  email: string;             // Contact email
  settings: TenantSettings;  // Configuration
  stats: TenantStats;        // Usage statistics
  status: 'active' | 'suspended' | 'deleted';
  created_at: string;        // ISO 8601 timestamp
  updated_at: string;        // Last update timestamp
}

interface TenantSettings {
  retention_days: number;
  batch_size: number;
  max_conversations_per_user: number;
  max_users: number;
  encryption_mode: 'platform' | 'byok';
  webhook_url?: string;
  webhook_events?: string[];
}

interface TenantStats {
  user_count: number;
  conversation_count: number;
  total_interactions: number;
  storage_bytes: number;
}

Next Steps

→Users API→Authentication Guide→Multi-Tenancy Deep Dive→Security Best Practices