Overview

𝚫base Platform API (1.0.0)

𝚫base Platform API

A fully managed, serverless event store that works out of the box.

Authentication

All API endpoints require authentication using either an API key or a JWT Bearer token. API key authentication is checked first, followed by JWT authentication as a fallback.

API Key Authentication (Recommended for Programmatic Access)

API keys provide a simple way to authenticate programmatic requests. The API key must be provided in the X-API-Key header:

X-API-Key: db_your_api_key_here

API Key Format:

• All API keys start with the prefix db_
• Keys are generated through the API key management interface
• Keys can be scoped to specific organizations and permissions
• Keys support IP whitelisting and expiration dates

Available Permissions: API keys support granular permissions organized by category:

• Event Stores: create:event_store, read:event_store, update:event_store, delete:event_store
• Events: read:events, write:events
• Streams: read:streams
• Subscriptions: manage:subscriptions
• WebSockets: connect:websockets
• API Keys (Self): create:api_keys, read:api_keys, update:api_keys, delete:api_keys
• API Keys (Organization): create:api_keys:org, read:api_keys:org, update:api_keys:org, delete:api_keys:org
• Administrative: * (full access)

Example Request:

curl -H "X-API-Key: db_1234567890abcdef" \
     -H "Content-Type: application/json" \
     https://api.deltabase.com/api/event-stores

JWT Bearer Token Authentication

JWT tokens are used for user session authentication and include tenant information.

The token must be provided in the Authorization header:

Authorization: Bearer your.jwt.token

JWT Token Structure: The JWT token must include the following claims:

• sub: User identifier
• tenantId: Tenant identifier
• role: User role within the tenant
• permissions: Array of permission strings
• exp: Token expiration timestamp

Example JWT Payload:

{
  "sub": "user_123",
  "tenantId": "tenant_xyz",
  "role": "admin",
  "permissions": ["read:events", "write:events", "manage:eventstore"],
  "exp": 1679142631
}

Authentication Precedence

1. API Key: If an X-API-Key header is present, it will be used for authentication
2. JWT Token: If no API key is provided, the system will check for a JWT token in the Authorization header
3. Cookie: As a final fallback, the system will check for an access_token cookie

Local Development Mode

When running locally via the CLI (deltabase dev), authentication is automatically bypassed for localhost requests. This allows developers to test the API without setting up authentication credentials.

Development Mode Features:

• Automatic authentication bypass for localhost and 127.0.0.1
• Requires DELTABASE_DEV_MODE=true environment variable
• Uses SystemActor for development requests
• All bypasses are logged for visibility
• Only works in development environments

Error Responses

• 401 Unauthorized: No valid authentication provided
• 403 Forbidden: Valid authentication but insufficient permissions
• 400 Bad Request: Invalid authentication format or missing required headers

• OpenAPI version: 3.0.0

Authentication

Bearer

JWT token containing tenant and user information

Security scheme type: http

Bearer format: JWT

ApiKey

API key for programmatic access (format: db_…)

Security scheme type: apiKey

Header parameter name: X-API-Key