> ## 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.

# PermissionSet Resource Configuration

> Define permissions that control what operations identities can perform on Edge Server

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:

```yaml theme={null}
auth:
  permission_sets:
    my_permissions:
      permissions: full
```

## Required Fields

| Field         | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| `permissions` | string | The permission level to grant. Currently only `"full"` is supported |

## Permission Levels

### Full Permissions

Currently, Edge Server supports a single permission level:

```yaml theme={null}
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.

<Info>
  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).
</Info>

## Complete Examples

### Basic Permission Set with Identity

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
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:
  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:

```yaml theme={null}
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:

```yaml theme={null}
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

## Related Resources

* [Identity Configuration](/edge-server/configuration/reference/identity-resource)
* [HttpServer Configuration](/edge-server/configuration/reference/http-server-resource)
* [Edge Server Security Guide](/edge-server/configuration/authentication)