Identity Resource Configuration

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

Field	Type	Description
`credential`	object	The credential this identity uses to authenticate with Edge Server
`permissions`	array	Array of permission set names that define what this identity can do

Optional Fields

Field	Type	Default	Description
`id`	string/null	Uses YAML key	Human-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]

Field	Type	Description
`api_key`	string	Base64-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: "REPLACE_ME_WITH_YOUR_URL"
      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: "REPLACE_ME_WITH_YOUR_URL"
      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: "REPLACE_ME_WITH_YOUR_URL"
      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: "REPLACE_ME_WITH_YOUR_URL"
      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

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

Important Notes

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

Authentication Guide - Complete guide to generating and managing API keys
PermissionSet Configuration
HttpServer Configuration

Ditto Edge Server

Getting Started

Reference

Identity Resource Configuration

Basic Configuration

Required Fields

Optional Fields

Credentials

API Key Credential

Generating API Keys

Permissions

Complete Examples

Complete Configuration with Authentication

Multiple Identities with Shared Permissions

Identity Without Custom ID

Using Identities with HTTP Servers

Security Best Practices

Important Notes

​Basic Configuration

​Required Fields

​Optional Fields

​Credentials

​API Key Credential

​Generating API Keys

​Permissions

​Complete Examples

​Complete Configuration with Authentication

​Multiple Identities with Shared Permissions

​Identity Without Custom ID

​Using Identities with HTTP Servers

​Security Best Practices

​Important Notes

​Related Resources

Basic Configuration

Required Fields

Optional Fields

Credentials

API Key Credential

Generating API Keys

Permissions

Complete Examples

Complete Configuration with Authentication

Multiple Identities with Shared Permissions

Identity Without Custom ID

Using Identities with HTTP Servers

Security Best Practices

Important Notes

Related Resources