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.
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 |
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
Next Steps
Audit Logs
Track all permission-related events.
Identity API
Manage users and roles programmatically.
