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

# Identity Resource Configuration

> Configure authentication identities for accessing Edge Server HTTP APIs

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.

<Info>
  For a complete guide on generating API keys and configuring authentication, see the [Authentication guide](/edge-server/configuration/authentication).
</Info>

## Basic Configuration

Identities are defined under the top-level `auth:` configuration:

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

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

<Warning>
  **Credentials must be unique** across all identities. Duplicating credentials across multiple identities is not allowed and will cause a configuration error.
</Warning>

### Generating API Keys

Use the Edge Server CLI to generate secure API key credentials:

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

```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]
```

See the [PermissionSet documentation](/edge-server/configuration/reference/permission-set-resource) for details on configuring permissions.

## Complete Examples

### Complete Configuration with Authentication

```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:
  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

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

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

```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:
  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):

```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: dev_mode  # No authentication required
```

## 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 identities. Each identity must have its own unique credential
2. **Audit Logging**: The `id` field (or YAML key if `id` is not set) appears in audit logs to identify who performed actions
3. **Permission Set References**: The `permissions` field must reference permission sets defined in the `permission_sets` section
4. **Authentication Flow**: When an HTTP request arrives with an API key, Edge Server validates it against all configured identities and checks the associated permissions

## Related Resources

* [Authentication Guide](/edge-server/configuration/authentication) - Complete guide to generating and managing API keys
* [PermissionSet Configuration](/edge-server/configuration/reference/permission-set-resource)
* [HttpServer Configuration](/edge-server/configuration/reference/http-server-resource)