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

# Database Authentication

> Configure the core database resource that manages data synchronization and storage

## Configuration

To run Edge Server, you need a configuration file in YAML format. This can be configured in two ways: Small Peers Only mode or Server Sync mode.

### Ditto SDK Devices (Small Peers Only)

Small Peers Only mode is a connection configuration type that restricts the Edge
Server to only synchronize with other small peers (SDK instances) in the mesh network over LAN,
BLE, and other local transport protocols.

The HTTP API is still accessible in this mode. See [HTTP Server Configuration](#http-server-configuration)

If you are using the Edge Server in a small peer only mode, you can use the following configuration:

```yaml theme={null}
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  subscriptions:
    - "SELECT * FROM tasks"
  auth:
    small_peer_only:
      offline_license_token: "YOUR_TOKEN_HERE"
```

### Cloud Sync

The Edge Server can authenticate with the cloud platform (either [Ditto-operated
Cloud or your own](/cloud/public-cloud/overview)) using your own authentication
webhook provider. You will need to provide the appropriate credentials in your
configuration file.

| Field          | Example                    | Description                                                                                      |
| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------ |
| `db_id`        | `a673b537-c02d-48da...`    | Also known as "AppID"                                                                            |
| `access_token` | `f72cbeb1-3735-59ef...`    | Your app's unique access token                                                                   |
| `provider`     | `__playgroundProvider`     | The provider name. If using Online Playground mode, use `__playgroundProvider` as your provider. |
| `auth_url`     | `REPLACE_ME_WITH_YOUR_URL` | The URL for the Ditto authentication service                                                     |

Replace the values with your actual Ditto AppID and Token from the Ditto Portal.

```yaml theme={null}
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  subscriptions:
    - "SELECT * FROM tasks"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://YOUR-AUTH-URL"
      provider: "__playgroundProvider"
      enable_cloud_sync: true  # Optional, defaults to false
```

## Authentication & Permissions

When using Small Peer Only mode or Playground mode, all reads and writes are
permitted. If you need more granular control over permissions, you can use
Ditto's authentication webhook provider system, which is configurable in the Ditto Portal.

Edge server is compatible with these webhook providers. You\
can configure connections to your webhook provider by providing the applicable
token and provider name in the [edge server configuration file](#cloud-sync).  To learn
more about custom authentication, see the [Authentication
Guide](/sdk/v5/auth-and-authorization/cloud-authentication).

## Best Practices

1. **Match db\_id across peers:** Ensure all devices that need to sync together use the same `db_id` value
2. **Descriptive device names:** Choose meaningful names for easier debugging and monitoring
3. **Limit subscriptions:** Only sync data you need to minimize bandwidth and storage
4. **Secure credentials:** Use environment variables or secrets management for tokens
5. **Plan persistence:** Choose appropriate storage locations with sufficient space

## Troubleshooting

### Database Won't Start

Check:

* `db_id` is valid UUIDv4 format
* Authentication credentials are correct
* Persistence directory has write permissions
* No other process is using the same database files

### Peers Not Syncing

Verify:

* Both peers have the same `db_id`
* Authentication modes are compatible
* Network connectivity exists between peers
* Firewall rules allow Ditto traffic

### High Disk Usage

Review:

* Subscription queries aren't too broad
* Log level isn't set to `verbose`
* Old log files are being rotated/cleaned

## Related Resources

* [Full DittoDatabase Configuration Reference](/edge-server/configuration/reference/ditto-database-resource)
* [Transport Configuration](/edge-server/configuration/transport-config)
* [Persistence Directory](/edge-server/configuration/persistence-directory)
* [HTTP Server](/edge-server/configuration/http-server)