Skip to main content
Authentication protects your Edge Server HTTP APIs by requiring clients to provide valid credentials. Edge Server uses API keys for authentication, combined with permission sets for authorization.

​
Overview

Edge Server authentication involves three components:
  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

Use the Edge Server CLI to generate secure API keys: 
edge-server api-key generate
This command outputs two values:
  • 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
Example output: 
Generated Private Key: dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=
Secure Public Hash: c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$
The API key is only shown once during generation. Store it securely (e.g., in a secrets manager or environment variable). The hash can be safely stored in your configuration file.

​
Validating API Keys

To verify that an API key matches its hash: 
edge-server api-key validate \
  --key "dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=" \
  --hash "c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$"
If valid, you’ll see: 
Key is valid
This is useful for:
  • Verifying credentials before deployment
  • Troubleshooting authentication issues

​
Configuring Authentication

​
Step 1: Create a Permission Set

Define what actions authenticated clients can perform: 
resources:
  api_permissions:
    resource_type: PermissionSet
    permissions: full  # Currently the only option
See the PermissionSet reference for details.

​
Step 2: Create an Identity

Add the API key hash and reference the permission set: 
resources:
  api_permissions:
    resource_type: PermissionSet
    permissions: full

  api_client:
    resource_type: Identity
    credential:
      api_key: "c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$"
    permissions: "api_permissions"
    id: "my-api-client"
The credential.api_key field contains the hash (not the original key). The original key is what clients send in HTTP requests.
See the Identity reference for details.

​
Step 3: Protect Your HTTP Server

Reference the identity in your HTTP server configuration: 
resources:
  api_permissions:
    resource_type: PermissionSet
    permissions: full

  api_client:
    resource_type: Identity
    credential:
      api_key: "c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=$"
    permissions: "api_permissions"
    id: "my-api-client"

  my_database:
    resource_type: DittoDatabase
    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"

  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["api_client"]  # Require authentication with this identity
    databases:
      main:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true
See the HTTP Server reference for details.

​
Using API Keys in HTTP Requests

Clients authenticate by including the API key in the Authorization header: 
curl -X POST http://127.0.0.1:8080/main/execute \
  -H "Authorization: Bearer dGVzdC1hcGkta2V5LTEyMzQ1Njc4OTA=" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "SELECT * FROM users",
    "args": {}
  }'
The format is: Authorization: Bearer <your-api-key>

​
Multiple Identities

You can configure multiple identities with different API keys: 
resources:
  # Permission sets
  admin_permissions:
    resource_type: PermissionSet
    permissions: full

  read_only_permissions:
    resource_type: PermissionSet
    permissions: full  # Currently all permissions are "full"

  # Identities
  admin_client:
    resource_type: Identity
    credential:
      api_key: "c2NyeXB0JGxuPTE2LHI9OCxwPTEkYWRtaW5oYXNoMTIzNDU2Nzg5MA=="
    permissions: "admin_permissions"
    id: "admin"

  readonly_client:
    resource_type: Identity
    credential:
      api_key: "c2NyeXB0JGxuPTE2LHI9OCxwPTEkcmVhZG9ubHloYXNoOTg3NjU0MzIx"
    permissions: "read_only_permissions"
    id: "readonly"

  # HTTP server accepting both identities
  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["admin_client", "readonly_client"]
    databases:
      main:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true
Both API keys can authenticate, allowing different clients to use different credentials. To disable authentication entirely: 
resources:
  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: null  # No authentication required
    databases:
      main:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true
Disabling authentication exposes your API to unauthorized access. Only do this in trusted development environments, never in production.

​
Best Practices

​
Key Generation

  1. Use the CLI: Always generate keys using 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 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

To rotate an API key:
  1. Generate a new key: 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

If clients receive 401 Unauthorized errors:
  1. Verify the key is correct: Use 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

If edge-server api-key validate reports the key is invalid:
  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