Skip to main content
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 CombinationUse Case
Read onlyPublic APIs, analytics dashboards
Read + WriteStandard application backend
Read + Write + AdminFull application management
Write onlyData ingestion pipelines
Read + Write + PayAutonomous 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:
LimitEnforced atEffect
expires_atPre-flightKey stops working after this timestamp
max_payment_per_txPer-writeSingle write cannot exceed this amount (uUSDC)
spend_allowancePer-writeCumulative lifetime cap (uUSDC)
allowed_target_appsPre-flightWhitelist 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

  1. Go to app.ondb.ai
  2. Log in to your account
  3. Select your application
  4. Navigate to the Security tab
  5. Enter a name for your key (e.g., “production-backend”, “staging-api”)
  6. Select the permissions (Read, Write, Admin)
  7. Click Generate New API Key
  8. Approve the transaction (small fee ~$0.001 USDC)
  9. 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:
  1. Go to the Security tab
  2. Click Load Keys to list all keys
  3. Find the key you want to revoke
  4. Click the Revoke button
  5. Confirm the revocation
  6. 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

PracticeDescription
Use environment variablesNever hardcode keys in source code
Principle of least privilegeCreate keys with only necessary permissions
Rotate keys regularlyRegenerate keys every 90 days
Separate environmentsUse different keys for dev/staging/production
Monitor usageCheck “Last Used” to detect unauthorized access
Immediate revocationRevoke 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