RBAC & Permissions

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:

Permissions

Atomic actions like attestations:mint or users:read. These are the building blocks.

Roles

Collections of permissions grouped by function. Roles like admin, issuer, or viewer.

Assignments

Binding users or API keys to roles. A user can have multiple roles.

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

Open the Roles page

Navigate to Roles in the console sidebar.

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.

Save the role

Click Create Role to save. The new role appears in the Custom Roles section of the Roles page.

Creating a custom role via the API

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:

{
  "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"]
  }
}

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

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

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Permission Model

Available Permissions

Attestation Permissions

Issuer Permissions

User Management Permissions

Administrative Permissions

Webhook permissions

Governance permissions

Settings permissions

System roles

Custom roles

Creating a custom role in the console

Creating a custom role via the API

Resource-level constraints

API Key Scopes vs. User Roles

Best Practices

Next Steps

Audit Logs

Identity API

​Permission Model

​Available Permissions

​Attestation Permissions

​Issuer Permissions

​User Management Permissions

​Administrative Permissions

​Webhook permissions

​Governance permissions

​Settings permissions

​System roles

​Custom roles

​Creating a custom role in the console

​Creating a custom role via the API

​Resource-level constraints

​API Key Scopes vs. User Roles

​Best Practices

​Next Steps

Audit Logs

Identity API

Permission Model

Available Permissions

Attestation Permissions

Issuer Permissions

User Management Permissions

Administrative Permissions

Webhook permissions

Governance permissions

Settings permissions

System roles

Custom roles

Creating a custom role in the console

Creating a custom role via the API

Resource-level constraints

API Key Scopes vs. User Roles

Best Practices

Next Steps