Security Settings

OnchainDB provides multiple layers of security including wallet-based authentication, spend authorization (authz), and encryption settings for your applications.

Wallet Authentication

OnchainDB Dashboard uses Keplr wallet for authentication. This ensures that only the wallet owner can manage their applications and API keys.

Connecting Your Wallet

Install the Keplr wallet extension
Navigate to dashboard.onchaindb.io
Click Connect Wallet
Approve the connection request in Keplr
Your wallet address is now linked to your session

OnchainDB supports both Celestia Mainnet and Celestia Mocha Testnet. The network is automatically detected from your Keplr configuration.

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 with Keplr to verify your identity and create a new session.

Request Signing

All sensitive operations require cryptographic signature verification:

Header	Description
`X-Wallet-Address`	Your wallet address
`X-Timestamp`	Request timestamp (5-minute validity window)
`X-Signature`	Base64-encoded signature
`X-Pubkey`	Your public key (base64-encoded)

This ensures that requests cannot be forged or replayed.

Spend Authorization (Authz)

Authz grants allow you to authorize the OnchainDB broker to execute payments on your behalf, enabling the Auto-Pay feature.

What is Authz?

Authz is a Cosmos SDK feature that lets you grant another address permission to execute specific transactions. For OnchainDB, this means:

The broker can deduct payments automatically for data operations
You don’t need to sign each individual transaction
Transactions are limited by your configured spend limit
Grants expire after one year

Setting Up Auto-Pay

Connect Wallet

Connect your Keplr wallet to the Dashboard

Configure Spend Limit

Enter your maximum spend limit in TIA (default: 10 TIA)

Grant Authorization

Click “Enable Auto-Pay” and approve the transaction in Keplr

Verify Status

Check that the green “Auto-Pay Enabled” badge appears

Authz Status Indicators

Status	Badge Color	Description
Enabled	Green	Auto-Pay is active with remaining balance
Disabled	Yellow	No authz grant, manual payments required
Low Balance	Orange	Remaining limit below threshold
Expired	Red	Grant has expired, needs renewal

Managing Your Authorization

From the Dashboard, you can:

View remaining limit: See how much of your spend authorization remains
Increase limit: Grant additional spend authorization
Revoke grant: Remove the broker’s authorization to spend on your behalf

Revoking your authz grant will disable Auto-Pay. You’ll need to provide payment proofs manually for all operations.

On-Chain Verification

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

Operations Requiring Verification

Operation	Transaction Memo	Fee
Generate API Key	`regenerate_key:{appId}`	~0.001 TIA
Revoke API Key	`revoke_key:{appId}:{keyHash}`	~0.001 TIA
List API Keys	`list_keys:{appId}`	~0.001 TIA
Update Encryption	`update_encryption:{appId}`	~0.001 TIA

This ensures that even if a session is compromised, attackers cannot modify your API keys without access to your wallet.

Verification Flow

Encryption Settings

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

Private Application

Making your application private encrypts all data by default:

Go to your app’s Encryption tab
Toggle Private App on
Approve the on-chain verification transaction

Private Collections

You can also encrypt specific collections while keeping others public:

Navigate to the Encryption tab
Select collections to encrypt
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 OnchainDB 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:

Checking your connected wallet address
Comparing against the app’s owner_wallet field
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.onchaindb.io/v1/store \
  -H "X-App-Key: your_app_key_here" \
  -H "X-User-Key: optional_user_key_for_auto_pay" \
  -H "Content-Type: application/json" \
  -d '{"collection": "posts", "data": [{"title": "Hello"}]}'

Security Implementation

Feature	Implementation
httpOnly Cookies	Session tokens protected from XSS
HMAC Signing	Token integrity verification
Timestamp Validation	5-minute replay attack window
On-Chain Verification	Wallet ownership proof
Immediate Invalidation	Revoked keys stop working instantly
One-Time Display	Keys shown once, never stored in plaintext

Troubleshooting

Session Expired

If you see “Session Expired” errors:

Sign the authentication message in Keplr
Your session will automatically renew
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

Auto-Pay Not Working

If automatic payments aren’t working:

Check your authz status in the Dashboard
Verify remaining spend limit is sufficient
Ensure the grant hasn’t expired
Confirm the user key is correctly configured

Next Steps

Authentication

Dual-key system and App Key permissions

Payment Flows

Manual vs automatic payment options

Best Practices

Security recommendations for production

Getting Started

Core Concepts

Querying Data

CRUD Operations

Payments

Advanced

AI Tools

Wallet Authentication

Connecting Your Wallet

Session Management

Request Signing

Spend Authorization (Authz)

What is Authz?

Setting Up Auto-Pay

Authz Status Indicators

Managing Your Authorization

On-Chain Verification

Operations Requiring Verification

Verification Flow

Encryption Settings

Private Application

Private Collections

App Ownership

Ownership Verification

API Key Security

Key Format

Key Headers

Security Implementation

Troubleshooting

Session Expired

Authorization Failed

Auto-Pay Not Working

Next Steps

Authentication

Payment Flows

Best Practices

Getting Started

Core Concepts

Querying Data

CRUD Operations

Payments

Advanced

AI Tools

​Wallet Authentication

​Connecting Your Wallet

​Session Management

​Request Signing

​Spend Authorization (Authz)

​What is Authz?

​Setting Up Auto-Pay

​Authz Status Indicators

​Managing Your Authorization

​On-Chain Verification

​Operations Requiring Verification

​Verification Flow

​Encryption Settings

​Private Application

​Private Collections

​App Ownership

​Ownership Verification

​API Key Security

​Key Format

​Key Headers

​Security Implementation

​Troubleshooting

​Session Expired

​Authorization Failed

​Auto-Pay Not Working

​Next Steps

Authentication

Payment Flows

Best Practices

Wallet Authentication

Connecting Your Wallet

Session Management

Request Signing

Spend Authorization (Authz)

What is Authz?

Setting Up Auto-Pay

Authz Status Indicators

Managing Your Authorization

On-Chain Verification

Operations Requiring Verification

Verification Flow

Encryption Settings

Private Application

Private Collections

App Ownership

Ownership Verification

API Key Security

Key Format

Key Headers

Security Implementation

Troubleshooting

Session Expired

Authorization Failed

Auto-Pay Not Working

Next Steps