Skip to main content
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

resources:
  my_identity:
    resource_type: Identity
    credential:
      api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
    permissions: "my_permission_set"  # Reference to a PermissionSet resource
    id: "service-account-1"  # Optional

​
Required Fields

FieldTypeDescription
resource_typestringMust be "Identity"
credentialobjectThe credential this identity uses to authenticate with Edge Server
permissionsstringReference to a PermissionSet resource that defines what this identity can do

​
Optional Fields

FieldTypeDefaultDescription
idstring/nullUses resource 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: 
credential:
  api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
FieldTypeDescription
api_keystringBase64-encoded string generated by Edge Server CLI
Credentials must be unique across all Identity resources. 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 credential generate-api-key
This will output a base64-encoded string that you can use in your configuration. The CLI handles proper hashing and encoding to ensure security.

​
Permissions

The permissions field references a PermissionSet resource defined elsewhere in your configuration. This separation allows you to reuse permission sets across multiple identities. 
resources:
  # Define a permission set
  admin_permissions:
    resource_type: PermissionSet
    permissions: full

  # Create an identity using those permissions
  admin_user:
    resource_type: Identity
    credential:
      api_key: "PHC_STRING_1"
    permissions: "admin_permissions"
See the PermissionSet documentation for details on configuring permissions.

​
Complete Examples

​
Basic Identity with Full Permissions

resources:
  # Define permissions
  full_access:
    resource_type: PermissionSet
    permissions: full

  # Define identity
  admin_identity:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkLi4u"
    permissions: "full_access"
    id: "admin-service-account"

  # Use identity in HTTP server
  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["admin_identity"]  # Restrict to this identity
    databases:
      my_db:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true

​
Multiple Identities with Shared Permissions

resources:
  # Shared permission set
  standard_permissions:
    resource_type: PermissionSet
    permissions: full

  # First identity
  service_a:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkS0VZX0E="
    permissions: "standard_permissions"
    id: "service-a"

  # Second identity
  service_b:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkS0VZX0I="
    permissions: "standard_permissions"
    id: "service-b"

  # HTTP server accepting both identities
  http_api:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["service_a", "service_b"]
    databases:
      main:
        db_id: "87654321-4321-4123-4321-210987654321"
        http_api: true

​
Identity Without Custom ID

When id is not specified, the resource key is used: 
resources:
  my_permission_set:
    resource_type: PermissionSet
    permissions: full

  backend_service:  # This name will be used as the identity ID
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkLi4u"
    permissions: "my_permission_set"
    # No 'id' field - "backend_service" will appear in audit logs

​
Using Identities with HTTP Servers

Identities are referenced in HttpServer resources to control authentication: 
resources:
  my_identity:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkLi4u"
    permissions: "some_permissions"

  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["my_identity"]  # Only this identity can authenticate
    databases:
      db1:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true
To disable authentication entirely (not recommended for production): 
api_server:
  resource_type: HttpServer
  listen_addr: "127.0.0.1:8080"
  auth: null  # No authentication required
  databases:
    db1:
      db_id: "12345678-1234-4123-1234-123456789012"
      http_api: true

​
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 Identity resources. Each identity must have its own unique credential
  2. Audit Logging: The id field (or resource key if id is not set) appears in audit logs to identify who performed actions
  3. Permission Set References: The permissions field must reference an existing PermissionSet resource by its resource key name
  4. Authentication Flow: When an HTTP request arrives with an API key, Edge Server validates it against all configured Identity resources and checks the associated permissions