> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ondb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Settings

> Authentication, authorization grants, and security configuration

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](https://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:

| 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.

## 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 USDC |
| Revoke API Key    | `revoke_key:{appId}:{keyHash}` | \~\$0.001 USDC |
| List API Keys     | `list_keys:{appId}`            | \~\$0.001 USDC |
| Update Encryption | `update_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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Dashboard
    participant Wallet
    participant Blockchain
    participant Broker

    User->>Dashboard: Request key generation
    Dashboard->>Wallet: Request transaction signature
    Wallet->>User: Approve transaction
    User->>Wallet: Confirm
    Wallet->>Blockchain: Broadcast transaction
    Blockchain-->>Dashboard: Transaction hash
    Dashboard->>Broker: Verify tx + generate key
    Broker-->>Dashboard: New API key
    Dashboard-->>User: Display key (one time)
```

## 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

<Tip>
  Use collection-level encryption when you need some public data (e.g., product listings) alongside private data (e.g., user preferences).
</Tip>

## 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

<Note>
  Application ownership cannot be transferred. To change ownership, create a new application with the desired wallet.
</Note>

## 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:

```bash theme={null}
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

| 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:

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">
    App Key and Agent Key permissions
  </Card>

  <Card title="Payment Flows" icon="credit-card" href="/concepts/payment-flows">
    Payment callback and pre-paid options
  </Card>

  <Card title="Best Practices" icon="check" href="/resources/best-practices">
    Security recommendations for production
  </Card>
</CardGroup>