Skip to main content
OnchainDB uses a dual-key authentication system to separate application-level operations from user-level operations.

​
Dual-Key System

App Key (X-App-Key)

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

User Key (X-User-Key)

  • Optional, enables Auto-Pay functionality
  • When user has granted authz to the broker, payments happen automatically
  • No payment callbacks needed when Auto-Pay is enabled

​
Configuration

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

const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'my_app',
  appKey: 'app_xxx...', // For writes
  userKey: 'user_yyy...' // For Auto-Pay reads/writes
});

​
App Key Permissions

App Keys support a three-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
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
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.

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

​
User Key and Auto-Pay

When you provide a userKey and the user has granted authorization (authz) to the broker, payments happen automatically without requiring payment callbacks.

​
Without Auto-Pay (Manual Payment)

// Client without userKey - requires payment callback
const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'my_app',
  appKey: 'app_xxx...'
});

// Must provide payment callback
await client.store(
  { collection: 'data', data: [{ content: 'example' }] },
  async (quote) => {
    const txHash = await wallet.pay(quote.brokerAddress, quote.totalCostTia);
    return { txHash, network: 'mocha-4' };
  }
);

​
With Auto-Pay (Automatic Payment)

// Client with userKey - automatic payments
const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'my_app',
  appKey: 'app_xxx...',
  userKey: 'user_yyy...' // User has granted authz
});

// No callback needed - payment is automatic
await client.store({
  collection: 'data',
  data: [{ content: 'example' }]
});

​
Managing App Keys

​
Generating a New Key

  1. Go to dashboard.onchaindb.io
  2. Connect your Keplr wallet
  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 on-chain transaction (small fee ~0.001 TIA)
  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 on-chain transaction
Revoked keys are immediately invalidated. Any applications using that key will receive authentication errors.

​
User Key

User keys are generated when users authenticate with your application and grant authorization (authz) to the OnchainDB broker for automatic payments. See Security Settings for details on authz grants.

​
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

// Server-side (Node.js)
const client = createClient({
  endpoint: process.env.ONCHAINDB_ENDPOINT,
  appId: process.env.ONCHAINDB_APP_ID,
  appKey: process.env.ONCHAINDB_APP_KEY
});

​
HTTPS Only

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

​
Next Steps

Security Settings

Wallet authentication and authz grants

Collections & Indexes

Learn about organizing your data

Payment Flows

Understand payment options