Skip to main content

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.

The Identity resource defines an authentication identity that can access Edge Server HTTP APIs. Each identity has a credential (such as an API key) and a set of permissions that control what operations they can perform.
For a complete guide on generating API keys and configuring authentication, see the Authentication guide.

​
Basic Configuration

Identities are defined under the top-level auth: configuration: 
auth:
  identities:
    my_identity:  # The key name is used as the identity name
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [my_permission_set]  # Array of permission set names
      id: "service-account-1"  # Optional: used in audit logs
  permission_sets:
    my_permission_set:
      permissions: full

​
Required Fields

FieldTypeDescription
credentialobjectThe credential this identity uses to authenticate with Edge Server
permissionsarrayArray of permission set names that define what this identity can do

​
Optional Fields

FieldTypeDefaultDescription
idstring/nullUses YAML keyHuman-readable identifier for this identity. Used in audit logs. If not provided, the YAML key name is used

​
Credentials

Credentials define how an identity authenticates with Edge Server. All credentials must be generated using the Edge Server CLI command.

​
API Key Credential

Currently, API key is the only supported credential type: 
auth:
  identities:
    my_identity:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [full_permissions]
FieldTypeDescription
api_keystringBase64-encoded string generated by Edge Server CLI
Credentials must be unique across all identities. Duplicating credentials across multiple identities is not allowed and will cause a configuration error.

​
Generating API Keys

Use the Edge Server CLI to generate secure API key credentials: 
# Generate an API key credential
ditto-edge-server api-key generate
This will output:
  • Generated Private Key: The secret clients use to authenticate (give to clients)
  • Secure Public Hash: The hash to store in your config (shown above)

​
Permissions

The permissions field is an array of permission set names defined in the same auth: configuration. This separation allows you to reuse permission sets across multiple identities. 
auth:
  permission_sets:
    admin_permissions:
      permissions: full
  identities:
    admin_user:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [admin_permissions]
See the PermissionSet documentation for details on configuring permissions.

​
Complete Examples

​
Complete Configuration with Authentication

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_identity:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [full_access]
      id: "admin-service-account"
  permission_sets:
    full_access:
      permissions: full

​
Multiple Identities with Shared Permissions

database:
  db_id: "87654321-4321-4123-4321-210987654321"
  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:
    service_a:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [standard_permissions]
      id: "service-a"
    service_b:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [standard_permissions]
      id: "service-b"
  permission_sets:
    standard_permissions:
      permissions: full

​
Identity Without Custom ID

When id is not specified, the YAML key is used: 
auth:
  identities:
    backend_service:  # This name will be used as the identity ID in audit logs
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [my_permission_set]
      # No 'id' field - "backend_service" will appear in audit logs
  permission_sets:
    my_permission_set:
      permissions: full

​
Using Identities with HTTP Servers

When identities are defined in the auth: configuration, the HTTP server automatically uses them for authentication: 
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:
    my_identity:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [some_permissions]
  permission_sets:
    some_permissions:
      permissions: full
To disable authentication entirely (not recommended for production): 
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: dev_mode  # No authentication required

​
Security Best Practices

  1. Generate credentials securely: Always use the Edge Server CLI to generate credentials. Never create API keys manually
  2. Unique credentials: Each identity must have a unique credential. Never reuse credentials across identities
  3. Meaningful IDs: Use descriptive id values to make audit logs easier to understand
  4. Principle of least privilege: Grant identities only the permissions they need
  5. Rotate credentials: Regularly rotate API keys by generating new credentials and updating your configuration
  6. Secure storage: Store credentials securely (e.g., in environment variables or secrets management systems) rather than committing them to version control

​
Important Notes

  1. Credential Uniqueness: The same credential cannot be used by multiple identities. Each identity must have its own unique credential
  2. Audit Logging: The id field (or YAML key if id is not set) appears in audit logs to identify who performed actions
  3. Permission Set References: The permissions field must reference permission sets defined in the permission_sets section
  4. Authentication Flow: When an HTTP request arrives with an API key, Edge Server validates it against all configured identities and checks the associated permissions