Roles

Role Types

System Roles — Permission Detail

admin

// admin — full system access within the tenant
permissions: [
  "tenant.*",         // all tenant management operations
  "workflow.*",       // all workflow operations
  "form.*",           // all form operations
  "iam.*",            // user management, role assignment, policy management
  "audit.*",          // full audit log access
  "security.*",       // security policy management
  "managed-identity.*"// managed identity lifecycle
]

manager

// manager — team and process management
permissions: [
  "workflow.design",
  "workflow.initiate",
  "workflow.view",
  "workflow.cancel",
  "form.create",
  "form.edit",
  "form.publish",
  "form.view",
  "user.view",         // can see team members but not manage them
  "audit.read"         // read-only audit access
]

user

// user — standard operational access
permissions: [
  "workflow.initiate",
  "workflow.view",      // own workflows only
  "form.submit",
  "form.view",          // forms assigned to them
  "task.complete"       // complete assigned HIL tasks
]

viewer

// viewer — read-only access
permissions: [
  "workflow.view",      // read-only workflow status
  "form.view"           // read-only form data (assigned resources)
]

RoleEntry Model

// IRoleDirectoryProvider returns RoleEntry objects
public class RoleEntry
{
    public required string RoleId       { get; init; }  // unique ID (int cast to string for Passport)
    public required string DisplayName  { get; init; }  // human-readable name
    public string? Description          { get; init; }  // optional description
}

// Example: search roles in a tenant
var roles = await roleDirectory.SearchRolesAsync(
    tenantId:   "tenant-abc",
    searchTerm: "finance",
    ct:         cancellationToken);

// Returns: [
//   { RoleId: "42", DisplayName: "Finance Manager", Description: "..." },
//   { RoleId: "43", DisplayName: "Finance Viewer",  Description: "..." }
// ]

Creating Tenant Roles (Admin API)

POST /passport/admin/roles
Authorization: Bearer {admin-token}
Content-Type: application/json

{
  "roleName": "finance-manager",
  "displayName": "Finance Manager",
  "description": "Access to payroll workflows and financial reports",
  "tenantId": "tenant-abc",
  "permissions": [
    "workflow.initiate",
    "workflow.view",
    "form.view",
    "report.finance.read",
    "report.payroll.read"
  ],
  "inheritsFrom": "manager"  // inherit all manager permissions + add these
}

// Response
{
  "roleId": "role-guid",
  "roleName": "finance-manager",
  "effectivePermissions": [
    "workflow.initiate", "workflow.view", "workflow.design",
    "form.view", "form.create", "form.edit", "form.publish",
    "report.finance.read", "report.payroll.read",
    "user.view", "audit.read"
  ]
}

Assigning Roles to Users

POST /passport/admin/users/{userId}/roles
Authorization: Bearer {admin-token}
Content-Type: application/json

{
  "roleIds": ["role-guid-finance-manager"],
  "tenantId": "tenant-abc",
  "assignedBy": "admin-user-guid",
  "expiresAt": null  // null = no expiry; set to ISO 8601 for time-limited assignment
}

// Revoke a role
DELETE /passport/admin/users/{userId}/roles/{roleId}
Authorization: Bearer {admin-token}

Role Hierarchy and Inheritance

Tenant roles can inherit from system roles using inheritsFrom. Effective permissions are the union of the parent's permissions and the child's additional permissions. There is no permission negation — a role cannot remove permissions inherited from a parent.