Skip to main content
OnDB provides multiple layers of security including wallet-based authentication and encryption settings for your applications.

​
Wallet Authentication

OnDB Dashboard uses wallet authentication to ensure that only the wallet owner can manage their applications and API keys.

​
Connecting Your Wallet

  1. Navigate to app.ondb.ai
  2. Click Connect Wallet
  3. Approve the connection request in your wallet
  4. Your wallet address is now linked to your session

​
Session Management

After connecting your wallet, a secure session is created:
  • Session Duration: 10 minutes
  • Auto-Renewal: Sessions automatically renew when you sign a new message
  • Secure Storage: Session tokens are stored in httpOnly cookies
When your session expires, you’ll be prompted to sign a message to verify your identity and create a new session.

​
Request Signing

All sensitive operations require cryptographic signature verification:
HeaderDescription
X-Wallet-AddressYour wallet address
X-TimestampRequest timestamp (5-minute validity window)
X-SignatureBase64-encoded signature
X-PubkeyYour public key (base64-encoded)
This ensures that requests cannot be forged or replayed.

​
On-Chain Verification

Critical operations require on-chain transaction verification to prove wallet ownership:

​
Operations Requiring Verification

OperationTransaction MemoFee
Generate API Keyregenerate_key:{appId}~$0.001 USDC
Revoke API Keyrevoke_key:{appId}:{keyHash}~$0.001 USDC
List API Keyslist_keys:{appId}~$0.001 USDC
Update Encryptionupdate_encryption:{appId}~$0.001 USDC
This ensures that even if a session is compromised, attackers cannot modify your API keys without access to your wallet.

​
Verification Flow

​
Encryption Settings

OnDB supports encryption for sensitive data at both the application and collection level.

​
Private Application

Making your application private encrypts all data by default:
  1. Go to your app’s Encryption tab
  2. Toggle Private App on
  3. Approve the on-chain verification transaction

​
Private Collections

You can also encrypt specific collections while keeping others public:
  1. Navigate to the Encryption tab
  2. Select collections to encrypt
  3. Save changes and approve the transaction
Use collection-level encryption when you need some public data (e.g., product listings) alongside private data (e.g., user preferences).

​
App Ownership

Each OnDB application is linked to a wallet address. Only the owner can:
  • Generate, list, or revoke API keys
  • Modify encryption settings
  • Update app configuration
  • View usage analytics

​
Ownership Verification

The Dashboard verifies ownership by:
  1. Checking your connected wallet address
  2. Comparing against the app’s owner_wallet field
  3. Returning 403 Forbidden if addresses don’t match
Application ownership cannot be transferred. To change ownership, create a new application with the desired wallet.

​
API Key Security

​
Key Format

App Keys are cryptographically generated tokens:
  • Length: 64 characters
  • Format: Alphanumeric with special characters
  • Storage: Only the hash is stored server-side

​
Key Headers

When making API requests, include the appropriate headers: 
curl -X POST https://api.ondb.io/v1/store \
  -H "X-App-Key: your_app_key_here" \
  -H "Content-Type: application/json" \
  -d '{"collection": "posts", "data": [{"title": "Hello"}]}'

​
Security Implementation

FeatureImplementation
httpOnly CookiesSession tokens protected from XSS
HMAC SigningToken integrity verification
Timestamp Validation5-minute replay attack window
On-Chain VerificationWallet ownership proof
Immediate InvalidationRevoked keys stop working instantly
One-Time DisplayKeys shown once, never stored in plaintext

​
Troubleshooting

​
Session Expired

If you see “Session Expired” errors:
  1. Sign the authentication message in your wallet
  2. Your session will automatically renew
  3. The original request will be retried

​
Authorization Failed

If you receive 403 Forbidden errors:
  • Verify you’re connected with the correct wallet
  • Check that you own the application
  • Ensure your session hasn’t expired

​
Next Steps

Authentication

App Key and Agent Key permissions

Payment Flows

Payment callback and pre-paid options

Best Practices

Security recommendations for production