Client Authentication

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.

​

Overview

1. Identity: Defines who can access the API (with a credential like an API key)
2. PermissionSet: Defines what actions are allowed
3. HttpServer: Specifies which identities can authenticate

​

Generating API Keys

ditto-edge-server api-key generate

• Generated Private Key: The secret key that clients use to authenticate (keep this secure)
• Secure Public Hash: The base64-encoded hash to store in your configuration

Generated Private Key: dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=
Secure Public Hash: c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$

​

Validating API Keys

ditto-edge-server api-key validate \
  --key "dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=" \
  --hash "c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$"

Key is valid

• Verifying credentials before deployment
• Troubleshooting authentication issues

​

Configuring Authentication

​

Step 1: Create a Permission Set

auth:
  permission_sets:
    full_permissions:
      permissions: full  # Currently the only option

​

Step 2: Create an Identity

auth:
  identities:
    api_client:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [full_permissions]
      id: "my-api-client"
  permission_sets:
    full_permissions:
      permissions: full

​

Step 3: Protect Your HTTP Server

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-server-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true

auth:
  identities:
    api_client:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [full_permissions]
      id: "my-api-client"
  permission_sets:
    full_permissions:
      permissions: full

​

Using API Keys in HTTP Requests

curl -X POST http://127.0.0.1:8080/execute \
  -H "Authorization: Bearer dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users"
  }'

​

Multiple Identities

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-server-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true

auth:
  identities:
    admin_client:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [admin_permissions]
      id: "admin"
    readonly_client:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [read_only_permissions]
      id: "readonly"
  permission_sets:
    admin_permissions:
      permissions: full
    read_only_permissions:
      permissions: full  # Currently all permissions are "full"

​

Disabling Authentication (Not Recommended)

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-server-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true

# No authentication required (dev mode only)
auth: dev_mode

​

Best Practices

​

Key Generation

1. Use the CLI: Always generate keys using ditto-edge-server api-key generate rather than creating them manually
2. One key per client: Generate unique API keys for each client or service
3. Validate before deploying: Use ditto-edge-server api-key validate to verify keys work before updating production configs

​

Key Storage

1. Store keys securely: Use environment variables, secrets managers, or secure vaults for API keys
2. Never commit keys: Don’t commit API keys to version control (add them to .gitignore)

​

Key Rotation

1. Generate a new key: ditto-edge-server api-key generate
2. Create a new Identity with the new hash
3. Add the new Identity to the HTTP server’s auth list (keeping the old one temporarily)
4. Update clients to use the new key
5. Verify clients are using the new key
6. Remove the old Identity from the auth list
7. Restart Edge Server to apply changes

​

Access Control

1. Use descriptive IDs: Give identities meaningful id values for audit logs (e.g., "production-api", "monitoring-service")
2. Separate permission sets: Create distinct permission sets for different roles (even if they currently have the same permissions)
3. Principle of least privilege: Plan to grant minimum necessary permissions when granular controls become available

​

Troubleshooting

​

Authentication Fails

1. Verify the key is correct: Use ditto-edge-server api-key validate to check the key matches the hash
2. Check the Identity resource ID: Ensure the HTTP server’s auth list references the correct Identity resource name
3. Verify the header format: Ensure the request uses Authorization: Bearer <key> format
4. Check Edge Server logs: Look for authentication-related errors in the server logs

​

Key Validation Fails

1. Check for whitespace: Ensure there’s no extra whitespace in the key or hash
2. Verify the hash format: Hashes should be base64-encoded strings starting with the algorithm identifier
3. Regenerate if needed: If unsure, generate a new key-hash pair and update your configuration

​

Related Resources

• Identity Configuration Reference
• PermissionSet Configuration Reference
• HTTP Server Configuration
• HTTP Server Configuration Reference