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 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' }] });
Getting Your Keys App Key
Go to dashboard.onchaindb.io
Select your application
Navigate to the “Security” tab
Generate a new App Key
User Key User keys are generated when users authenticate with your application and grant authorization to the OnchainDB broker for automatic payments.
Security Best Practices Never expose your App Key in client-side code. Use environment variables and server-side APIs for write operations.
// Server-side (Node.js) const client = createClient ({ endpoint: process . env . ONCHAINDB_ENDPOINT , appId: process . env . ONCHAINDB_APP_ID , appKey: process . env . ONCHAINDB_APP_KEY });
Next Steps 
