#Overview

Roles are named collections of permissions in the Enterprise Stack RBAC model. They provide a way to group related permissions together and assign them to principals (Accounts, API Keys, or external IAM identities).

#Key Concepts

#Role Structure

A role consists of:

Name: A human-readable identifier (e.g., "Issuer Operator")
ID: A resource path identifier (e.g., waltid.tenantA.issuer-role)
Permissions: A collection of permission grants and denials

#Permission Operations

Each permission in a role has an operation type:

Operation	Description
`ADD`	Grants the permission (allow rule)
`REMOVE`	Denies the permission (deny rule that overrides allows)

#Role Assignment

Roles can be assigned to:

Accounts: User accounts authenticated via email/password or external IAM
API Keys: Machine-to-machine authentication tokens

A principal can have multiple roles assigned, and their effective permissions are the combination of all role grants minus any denials.

#Common Role Patterns

#Administrative Roles

Role	Typical Permissions
Organization Admin	`all` on organization scope
Tenant Admin	`all` on specific tenant scope
Service Admin	`all` on specific service scope

#Operational Roles

Role	Typical Permissions
Issuer Operator	Issue credentials, view sessions
Verifier Operator	Create verification sessions, view results
Key Manager	Generate, import, and manage cryptographic keys

#Compliance Roles

Role	Typical Permissions
Auditor	View events and resource trees (read-only)
Security Officer	View configurations, manage policies

#Role Hierarchy Example

Organization: waltid
│
├── Role: waltid.org-admin (Organization Admin)
│   └── Permissions: all on waltid
│
├── Tenant: waltid.production
│   │
│   ├── Role: waltid.production.tenant-admin
│   │   └── Permissions: all on waltid.production
│   │
│   ├── Role: waltid.production.issuer-ops
│   │   └── Permissions: issuer-credential-issue, issuer-session-view
│   │
│   └── Role: waltid.production.auditor
│       └── Permissions: view-events, view-resource-tree
│
└── Tenant: waltid.sandbox
    │
    └── Role: waltid.sandbox.tenant-admin
        └── Permissions: all on waltid.sandbox

#Best Practices

Create purpose-specific roles: Instead of granting broad permissions, create roles tailored to specific job functions
Use descriptive names: Name roles clearly to indicate their purpose (e.g., "Production Issuer Operator" rather than "Role 1")
Apply least privilege: Grant only the minimum permissions required for the role's function
Use deny rules sparingly: Deny rules (REMOVE operation) are useful for creating exceptions but can make permission management complex
Document role purposes: Maintain documentation of what each role is intended for and who should have it

#Get Started

Creating Roles - Step-by-step guide to create and configure roles
Permissions Reference - Complete list of available permissions
Assign Role to Account - How to assign roles to user accounts
Assign Role to API Key - How to assign roles to API keys

Last updated on May 6, 2026

Query Resources by Metadata Create Roles