Authentication

OnDB uses two key types to authenticate application operations and autonomous agent operations.

Key Types

App Key (X-App-Key)

Required for write operations
Identifies the application
Used for app-level permissions

Agent Key (X-Agent-Key)

App Key with Pay permission
Enables autonomous agents to pay other apps inline
Configurable spend limits and target app whitelisting

Configuration

TypeScript

import { createClient } from '@ondb/sdk';

const client = createClient({
  endpoint: 'https://api.ondb.io',
  appId: 'my_app',
  appKey: 'app_xxx...' // For writes
});

App Key Permissions

App Keys support a four-tier permission system, allowing you to create keys with granular access control:

Read

Query data
Read documents
Access collections
View indexes

Write

Store data
Update documents
Delete documents
Create collections

Admin

Manage indexes
Configure encryption
App-level settings
Full access

Pay

Agent Key permission
Pay other apps inline via USDC
Configurable spend limits
Target app whitelisting

When generating an App Key from the Dashboard, you can select any combination of these permissions:

Permission Combination	Use Case
Read only	Public APIs, analytics dashboards
Read + Write	Standard application backend
Read + Write + Admin	Full application management
Write only	Data ingestion pipelines
Read + Write + Pay	Autonomous AI agents accessing paid data

Create separate keys with minimal permissions for different parts of your application. A read-only key for your frontend proxy and a write key for your backend services.

Agent Keys

An Agent Key is an App Key with the Pay permission. It enables autonomous agents to pay other apps inline when storing or querying their data, using USDC.

Generating an Agent Key

// Via API
const response = await fetch(`${endpoint}/api/apps/${agentAppId}/regenerate-key`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    permissions: ['Pay'],
    pay_limits: {
      max_payment_per_tx: 1_000_000,       // 1 USDC max per transaction
      spend_allowance: 50_000_000,          // 50 USDC lifetime cap
      expires_at: '2026-06-01',             // Key expiry
      allowed_target_apps: ['target_app']   // Whitelist (omit to allow all)
    }
  })
});
// Key is returned once and never stored -- save it immediately

Using an Agent Key

TypeScript

import { createClient } from '@ondb/sdk';

const agent = createClient({
  endpoint: 'https://api.ondb.io',
  appId: 'my_agent_app',
  agentKey: 'app_a3f9...'  // X-Agent-Key header — key must have Pay permission
});

// Write to another app's collection -- payment is automatic
await agent.store({
  collection: 'target_app::data',
  data: [{ content: 'example' }]
});

// Read from another app's collection
const result = await agent.queryBuilder()
  .collection('target_app::premium_data')
  .selectAll()
  .execute();

How Agent Auto-Pay Works

Writes: The broker handles payment automatically in a background task:

1. Agent sends POST /store with X-Agent-Key header
2. Pre-flight: verify Pay permission, expiry, target app whitelist
3. Return 200 + ticket_id immediately
4. Background task:
   a. Calculate write cost (USDC)
   b. Verify amount <= max_payment_per_tx
   c. Verify cumulative spend <= spend_allowance
   d. Broker transfers USDC from agent wallet to target app wallet
   f. Credit target app wallet, record spend against allowance
   g. Write data to storage

Reads: The agent key authenticates the request. If the collection has paid fields, the standard PaymentRequiredError flow applies separately.

Pay Limits

All limits are optional — omit any to leave it uncapped. Limits are enforced fail-fast in order:

Limit	Enforced at	Effect
`expires_at`	Pre-flight	Key stops working after this timestamp
`max_payment_per_tx`	Per-write	Single write cannot exceed this amount (uUSDC)
`spend_allowance`	Per-write	Cumulative lifetime cap (uUSDC)
`allowed_target_apps`	Pre-flight	Whitelist of app IDs the key can pay into

interface PayLimits {
  expires_at?: string;           // ISO 8601 expiry time
  max_payment_per_tx?: number;   // Max USDC per transaction (6 decimals)
  spend_allowance?: number;      // Lifetime spend cap in USDC base units
  allowed_target_apps?: string[]; // Whitelist of target app IDs
}

1 USDC = 1,000,000 uUSDC (6 decimals). A max_payment_per_tx of 5_000_000 means 5 USDC.

App Key Usage

The App Key (X-App-Key header) is required for all write operations:

Creating documents
Updating documents
Deleting documents
Creating indexes
Creating collections
Managing views

TypeScript

// App key is automatically included in all requests
const result = await client.store({
  collection: 'posts',
  data: [{ title: 'Hello World', content: 'My first post' }]
});

Managing App Keys

Generating a New Key

Go to app.ondb.ai
Log in to your account
Select your application
Navigate to the Security tab
Enter a name for your key (e.g., “production-backend”, “staging-api”)
Select the permissions (Read, Write, Admin)
Click Generate New API Key
Approve the transaction (small fee ~$0.001 USDC)
Copy your key immediately - it will only be shown once

App Keys are only displayed once at creation time. Store them securely in your environment variables or secrets manager immediately after generation.

Listing Existing Keys

From the Security tab, click Load Keys to view all your active App Keys. For each key you can see:

Key Hash: First 16 characters of the key hash for identification
Name: The name you assigned when creating the key
Permissions: Visual badges showing Read/Write/Admin access
Created: When the key was generated
Last Used: Most recent API request with this key

Revoking a Key

If a key is compromised or no longer needed:

Go to the Security tab
Click Load Keys to list all keys
Find the key you want to revoke
Click the Revoke button
Confirm the revocation
Approve the transaction

Revoked keys are immediately invalidated. Any applications using that key will receive authentication errors.

Security Best Practices

Never expose your App Key in client-side code. Use environment variables and server-side APIs for write operations.

Key Management Guidelines

Practice	Description
Use environment variables	Never hardcode keys in source code
Principle of least privilege	Create keys with only necessary permissions
Rotate keys regularly	Regenerate keys every 90 days
Separate environments	Use different keys for dev/staging/production
Monitor usage	Check “Last Used” to detect unauthorized access
Immediate revocation	Revoke compromised keys immediately

Server-Side Configuration

TypeScript

// Server-side (Node.js)
const client = createClient({
  endpoint: process.env.ONDB_ENDPOINT,
  appId: process.env.ONDB_APP_ID,
  appKey: process.env.ONDB_APP_KEY
});

HTTPS Only

Always use HTTPS when communicating with OnDB APIs. Never send App Keys over unencrypted connections.

Next Steps

Security Settings

Authentication and authz grants

Collections & Indexes

Learn about organizing your data

Payment Flows

Understand payment options

Getting Started

Core Concepts

Querying Data

CRUD Operations

Payments

Advanced

AI Tools

Key Types

App Key (X-App-Key)

Agent Key (X-Agent-Key)

Configuration

App Key Permissions

Read

Write

Admin

Pay

Agent Keys

Generating an Agent Key

Using an Agent Key

How Agent Auto-Pay Works

Pay Limits

App Key Usage

Managing App Keys

Generating a New Key

Listing Existing Keys

Revoking a Key

Security Best Practices

Key Management Guidelines

Server-Side Configuration

HTTPS Only

Next Steps

Security Settings

Collections & Indexes

Payment Flows

​Key Types

App Key (X-App-Key)

Agent Key (X-Agent-Key)

​Configuration

​App Key Permissions

Read

Write

Admin

Pay

​Agent Keys

​Generating an Agent Key

​Using an Agent Key

​How Agent Auto-Pay Works

​Pay Limits

​App Key Usage

​Managing App Keys

​Generating a New Key

​Listing Existing Keys

​Revoking a Key

​Security Best Practices

​Key Management Guidelines

​Server-Side Configuration

​HTTPS Only

​Next Steps

Security Settings

Collections & Indexes

Payment Flows

Key Types

Configuration

App Key Permissions

Agent Keys

Generating an Agent Key

Using an Agent Key

How Agent Auto-Pay Works

Pay Limits

App Key Usage

Managing App Keys

Generating a New Key

Listing Existing Keys

Revoking a Key

Security Best Practices

Key Management Guidelines

Server-Side Configuration

HTTPS Only

Next Steps