Skip to main content
The PermissionSet resource defines a collection of permissions that can be granted to one or more Identity resources. Permission sets allow you to centrally manage authorization rules and reuse them across multiple identities.

​
Basic Configuration

Permission sets are defined under the top-level auth: configuration: 
auth:
  permission_sets:
    my_permissions:
      permissions: full

​
Required Fields

FieldTypeDescription
permissionsstringThe permission level to grant. Currently only "full" is supported

​
Permission Levels

​
Full Permissions

Currently, Edge Server supports a single permission level: 
permissions: full
The full permission level grants complete access to:
  • All HTTP API endpoints
  • All data plane operations
  • All database operations on Edge Server
This permission level has no restrictions and allows the identity to perform any action available through the Edge Server API.
Future versions of Edge Server may introduce more granular permission levels to support fine-grained access control (e.g., read-only permissions, per-database permissions, or per-endpoint permissions).

​
Complete Examples

​
Basic Permission Set with Identity

auth:
  permission_sets:
    admin_permissions:
      permissions: full
  identities:
    admin_user:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [admin_permissions]

​
Shared Permission Set for Multiple Identities

A common pattern is to define one permission set and reuse it across multiple identities: 
auth:
  permission_sets:
    standard_access:
      permissions: full
  identities:
    service_a:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [standard_access]
    service_b:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [standard_access]
    service_c:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [standard_access]

​
Complete Configuration with 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:
  permission_sets:
    api_permissions:
      permissions: full
  identities:
    api_client:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [api_permissions]
      id: "api-client-service"

​
Using Permission Sets

​
Referencing in Identities

Permission sets are referenced by their key name in the permissions array of identities: 
auth:
  permission_sets:
    my_perms:  # Permission set key
      permissions: full
  identities:
    my_identity:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [my_perms]  # Reference the permission set key

​
Multiple Permission Sets

You can define multiple permission sets for organizational purposes, even if they currently all grant full permissions: 
auth:
  permission_sets:
    admin_permissions:
      permissions: full
    service_permissions:
      permissions: full
    monitor_permissions:
      permissions: full
  identities:
    human_admin:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [admin_permissions]
    backend_service:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [service_permissions]
    monitoring_agent:
      credential:
        api_key: "BASE64_ENCODED_STRING_GENERATED_BY_CLI"
      permissions: [monitor_permissions]
While all three permission sets currently grant full access, this structure allows you to easily adjust permissions when more granular controls become available.

​
Authorization Flow

When an authenticated request arrives at an Edge Server HTTP API:
  1. Authentication: The API key from the request is validated against configured identities
  2. Permission Lookup: The identity’s permissions array is used to locate the associated permission sets
  3. Authorization Check: The permission set’s permissions value determines what operations are allowed
  4. Request Processing: If authorized, the request proceeds; otherwise, an authorization error is returned

​
Future Enhancements

Future versions of Edge Server may introduce additional permission levels such as:
  • Read-only: Allow read operations but deny writes
  • Per-database: Grant access to specific databases only
  • Per-endpoint: Allow access to specific API endpoints
  • Custom permissions: Define custom permission rules using a policy language
These enhancements will allow more fine-grained access control while maintaining backward compatibility with existing configurations.

​
Best Practices

  1. Semantic naming: Use descriptive names for permission sets that reflect their intended purpose (e.g., admin_permissions, read_only_permissions, service_account_permissions)
  2. Reuse permission sets: Define permission sets once and reference them from multiple identities to maintain consistency
  3. Prepare for granularity: Organize permission sets by role or function now, even if they all grant full permissions, to make future permission refinements easier
  4. Document intent: Add comments in your YAML configuration to explain the intended use of each permission set

​
Important Notes

  1. Current Limitation: Only "full" permissions are currently supported. Attempting to use other values will result in a configuration error
  2. Key Name Reference: Identities reference permission sets by their YAML key name in the permission_sets section
  3. Validation: Edge Server validates that all identities reference valid permission sets at startup
  4. No Dynamic Updates: Changes to permission sets require Edge Server restart to take effect