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

resources:
  my_permissions:
    resource_type: PermissionSet
    permissions: full

​
Required Fields

FieldTypeDescription
resource_typestringMust be "PermissionSet"
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

resources:
  # Define a permission set
  admin_permissions:
    resource_type: PermissionSet
    permissions: full

  # Use it with an identity
  admin_user:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkLi4u"
    permissions: "admin_permissions"

​
Shared Permission Set for Multiple Identities

A common pattern is to define one permission set and reuse it across multiple identities: 
resources:
  # Define the permission set once
  standard_access:
    resource_type: PermissionSet
    permissions: full

  # Multiple identities can reference the same permission set
  service_a:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkS0VZX0E="
    permissions: "standard_access"

  service_b:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkS0VZX0I="
    permissions: "standard_access"

  service_c:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkS0VZX0M="
    permissions: "standard_access"

​
Complete Configuration with HTTP Server

resources:
  # Database
  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"

  # Permission set
  api_permissions:
    resource_type: PermissionSet
    permissions: full

  # Identity using the permission set
  api_client:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkLi4u"
    permissions: "api_permissions"
    id: "api-client-service"

  # HTTP server requiring authentication with this identity
  http_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: ["api_client"]
    databases:
      main:
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true

​
Using Permission Sets

​
Referencing in Identities

Permission sets are referenced by their resource key name in Identity configurations: 
resources:
  my_perms:  # Resource key
    resource_type: PermissionSet
    permissions: full

  my_identity:
    resource_type: Identity
    credential:
      api_key: "..."
    permissions: "my_perms"  # Reference the resource key

​
Multiple Permission Sets

You can define multiple permission sets for organizational purposes, even if they currently all grant full permissions: 
resources:
  # Permission set for human administrators
  admin_permissions:
    resource_type: PermissionSet
    permissions: full

  # Permission set for automated services
  service_permissions:
    resource_type: PermissionSet
    permissions: full

  # Permission set for monitoring tools
  monitor_permissions:
    resource_type: PermissionSet
    permissions: full

  # Different identities use different permission sets
  human_admin:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkQURNSU4="
    permissions: "admin_permissions"

  backend_service:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkU1ZD"
    permissions: "service_permissions"

  monitoring_agent:
    resource_type: Identity
    credential:
      api_key: "YXJnb24yaWQkdj0xOSRtPTE5NDU2LHQ9MixwPTEkTU9O"
    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 Identity resources
  2. Permission Lookup: The Identity’s permissions field is used to locate the associated PermissionSet
  3. Authorization Check: The PermissionSet’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. Resource Key Reference: Identities reference permission sets by their YAML resource key name, not by any internal ID
  3. Validation: Edge Server validates that all Identity resources reference valid PermissionSet resources at startup
  4. No Dynamic Updates: Changes to permission sets require Edge Server restart to take effect