> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RBAC & Permissions

> Role-based access control and permission management.

Truthlocks implements role-based access control (RBAC) to manage who can perform which actions. This guide explains the permission model.

## Permission Model

The Truthlocks permission model consists of three layers:

<Steps>
  <Step title="Permissions">
    Atomic actions like `attestations:mint` or `users:read`. These are the
    building blocks.
  </Step>

  <Step title="Roles">
    Collections of permissions grouped by function. Roles like `admin`,
    `issuer`, or `viewer`.
  </Step>

  <Step title="Assignments">
    Binding users or API keys to roles. A user can have multiple roles.
  </Step>
</Steps>

## Available Permissions

### Attestation Permissions

| Permission            | Description                                         |
| --------------------- | --------------------------------------------------- |
| `attestations:mint`   | Create new attestations                             |
| `attestations:read`   | View attestation details and download proof bundles |
| `attestations:revoke` | Revoke existing attestations                        |
| `attestations:*`      | All attestation permissions                         |

### Issuer Permissions

| Permission      | Description                      |
| --------------- | -------------------------------- |
| `issuers:read`  | View issuer information and keys |
| `issuers:write` | Create issuers, register keys    |
| `issuers:*`     | All issuer permissions           |

### User Management Permissions

| Permission       | Description                              |
| ---------------- | ---------------------------------------- |
| `users:read`     | View users and role assignments          |
| `users:write`    | Invite users, assign roles, remove users |
| `api-keys:read`  | View API keys (without secrets)          |
| `api-keys:write` | Create and revoke API keys               |

### Administrative Permissions

| Permission           | Description                 |
| -------------------- | --------------------------- |
| `audit:read`         | Query audit logs            |
| `governance:approve` | Approve governance requests |
| `governance:suspend` | Suspend active issuers      |
| `*`                  | Superadmin: all permissions |

### Webhook permissions

| Permission       | Description                              |
| ---------------- | ---------------------------------------- |
| `webhooks:read`  | View webhook endpoints and delivery logs |
| `webhooks:write` | Create, update, and delete endpoints     |
| `webhooks:*`     | All webhook permissions                  |

### Governance permissions

| Permission           | Description                 |
| -------------------- | --------------------------- |
| `governance:read`    | View governance requests    |
| `governance:approve` | Approve governance requests |
| `governance:suspend` | Suspend active issuers      |
| `governance:*`       | All governance permissions  |

### Settings permissions

| Permission       | Description                                         |
| ---------------- | --------------------------------------------------- |
| `settings:read`  | View tenant and organization settings               |
| `settings:write` | Update branding, domains, email, and other settings |
| `settings:*`     | All settings permissions                            |

## System roles

Truthlocks provisions a set of system roles automatically when your tenant is created. System roles cannot be edited or deleted.

| Role             | Description                                                     | Key permissions                                        |
| :--------------- | :-------------------------------------------------------------- | :----------------------------------------------------- |
| **Tenant Admin** | Full access to all resources within the tenant                  | `*` (superadmin)                                       |
| **Org Admin**    | Manage a single organization's issuers, users, and attestations | `issuers:*`, `attestations:*`, `users:*`, `audit:read` |
| **Issuer Admin** | Manage issuers and mint attestations                            | `issuers:*`, `attestations:*`                          |
| **Auditor**      | Read-only access for monitoring and compliance                  | `attestations:read`, `issuers:read`, `audit:read`      |

You can view system roles from the **Roles** page in the console. Each role shows its name, description, and a **System** badge.

## Custom roles

Create custom roles to define access permissions tailored to your team's structure. Custom roles are available on all plans.

### Creating a custom role in the console

<Steps>
  <Step title="Open the Roles page">
    Navigate to **Roles** in the console sidebar.
  </Step>

  <Step title="Click Create Custom Role">
    The **Create Custom Role** button opens a dialog where you provide:

    * **Role Name** — a descriptive name for the role (for example, `Developer` or `Compliance Officer`).
    * **Description** — a brief explanation of what the role is for.
  </Step>

  <Step title="Save the role">
    Click **Create Role** to save. The new role appears in the **Custom Roles** section of the Roles page.
  </Step>
</Steps>

### Creating a custom role via the API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/roles \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "attestation_minter",
    "description": "Can only mint attestations for specific issuers",
    "permissions": ["attestations:mint", "attestations:read", "issuers:read"],
    "constraints": {
      "issuer_ids": ["issuer-uuid-1", "issuer-uuid-2"]
    }
  }'
```

### Resource-level constraints

Custom roles support optional constraints that limit permissions to specific resources:

```json theme={null}
{
  "name": "regional_auditor",
  "description": "Audit access scoped to EU issuers only",
  "permissions": ["attestations:read", "issuers:read", "audit:read"],
  "constraints": {
    "issuer_ids": ["eu-issuer-uuid-1", "eu-issuer-uuid-2"]
  }
}
```

<Info>
  Resource-level constraints (such as limiting to specific issuers) are
  available on Enterprise plans.
</Info>

## API Key Scopes vs. User Roles

Both API keys and users have permissions, but they work differently:

| Aspect      | API Key Scopes                 | User Roles                   |
| ----------- | ------------------------------ | ---------------------------- |
| Assignment  | Set at key creation, immutable | Can be changed anytime       |
| Audit Trail | Actions logged as API key ID   | Actions logged as user email |
| Multiple    | One key = one set of scopes    | User can have multiple roles |
| Use Case    | Server-to-server integration   | Human users via UI/dashboard |

## Best Practices

* **Least Privilege:** Grant only the permissions needed for each role
* **Separate Duty:** Don't give one role both `attestations:mint` and `governance:approve`
* **Regular Audits:** Review role assignments quarterly
* **Use API Keys for Automation:** Don't share user credentials for scripts
* **Document Custom Roles:** Keep a record of why custom roles were created

## Next Steps

<CardGroup cols={2}>
  <Card title="Audit Logs" icon="list-check" href="/security/audit">
    Track all permission-related events.
  </Card>

  <Card title="Identity API" icon="user-shield" href="/api-reference/identity/orgs">
    Manage users and roles programmatically.
  </Card>
</CardGroup>