RBAC & Permissions

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

Permission Model

The Truthlock permission model consists of three layers:

1. Permissions

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

2. Roles

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

3. 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 pending issuers
`governance:suspend`	Suspend active issuers
`*`	Superadmin: all permissions

Built-in Roles

Truthlock provides predefined roles for common use cases:

Admin

Full access to all resources within the tenant.

permissions: ["*"]

Issuer Manager

Manage issuers and mint attestations.

permissions: [
  "issuers:*",
  "attestations:*"
]

Governance Admin

Approve, suspend, and reinstate issuers.

permissions: [
  "issuers:read",
  "governance:*"
]

Viewer

Read-only access for monitoring and auditing.

permissions: [
  "attestations:read",
  "issuers:read",
  "audit:read"
]

Custom Roles

Enterprise tier customers can create custom roles with specific permissions:

// Example: Create a role for attestation minters only
{
  "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"]
  }
}

Enterprise Feature: Custom roles with resource-level constraints (e.g., limiting to specific issuers) are only available on Enterprise tier.

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