Overview
Passinstance implements a hierarchical, least-privilege Role-Based Access Control (RBAC) engine (Team Permissions API at /api/v1/rbac/*, managed visually in the Dashboard under Workspace Settings -> Members & Roles: /settings/workspace/members, /settings/workspace/roles, and /settings/workspace/roles/permission-matrix) that separates Organization-level governance (OrganizationMemberRole: OWNER | ADMIN | MEMBER) from Workspace-level operational roles. Administrators can invite team members (POST /api/v1/users/invitations), construct custom roles with inheritance trees, enforce Two-Factor Authentication (2FA) per role, and restrict operators to specific pass templates (template-access).
Multi-Level RBAC & Template Scoping Architecture
Important: Authorization checks are enforced strictly server-side at the NestJS controller and service layers. Restricting a custom role via
template-accessguarantees that the operator cannot query, mutate, or export passes belonging to unapproved templates even if they call the REST API directly.
Organization Roles vs. Workspace Roles
Passinstance distinguishes between umbrella Organization membership and individual Workspace (Customer) permissions:
| Tier & Role | Scope | Core Capabilities & Permissions |
|---|---|---|
Organization OWNER | All Workspaces in Organization | Full control over organization billing rollups (GET /api/v1/organizations/current/billing-summary), workspace creation/deletion, SAML 2.0 SSO configuration, and owner transfers. |
Organization ADMIN | Assigned / All Workspaces | Manage team invitations, workspace settings, Apple/Google signing certificates, API keys (api:keys-manage), and webhooks. |
Workspace Editor (MEMBER) | Single Workspace | Create and edit pass templates, configure mechanics and tiers, run CSV batch imports, and execute Delivery Center campaigns. |
Workspace Operator | Single Workspace / Scoped Templates | Issue or look up individual passes, operate web/mobile validation scanners, and view scoped scan reports without access to billing or API keys. |
Custom Roles, Inheritance & Permission Scopes (Team Permissions API)
When built-in roles are too broad for specialized teams (for example, an external marketing agency or regional store manager), Workspace Admins can define custom roles under Account → Team Members → Roles & Permissions.
Core RBAC API Endpoints
| Endpoint | HTTP Verb | Description |
|---|---|---|
/api/v1/rbac/roles | GET | Lists all built-in and custom roles defined within the active workspace. |
/api/v1/rbac/roles | POST | Creates a custom RBAC role with explicit permission tokens and optional parent role inheritance. |
/api/v1/rbac/roles/:roleId | PUT | Updates a custom role's name, description, requireTwoFactor policy, or permission set. |
/api/v1/rbac/roles/:roleId | DELETE | Deletes a custom role (fails safely if active team members are still assigned to the role). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Returns the parent-child inheritance graph for the specified role. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Computes the effective union of direct permissions and permissions inherited from parent roles. |
/api/v1/rbac/roles/:roleId/template-access | POST | Binds the role to an explicit allowlist of templateIds (accessMode: 'SCOPED'). |
Creating a Custom Role with Inheritance
POST /api/v1/rbac/roles HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
]
}
Response Payload (201 Created)
{
"id": "rol_01933210-8b44-7c00-9e12-445566778899",
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"isSystemRole": false,
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
],
"createdAt": "2026-11-15T23:34:30.000Z"
}
Restricting a Role to Specific Templates (template-access)
To isolate a custom role so its members can only view and manage passes belonging to specific templates:
POST /api/v1/rbac/roles/rol_01933210-8b44-7c00-9e12-445566778899/template-access HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"accessMode": "SCOPED",
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"allowedActions": ["READ", "ISSUE_PASS", "SCAN_PASS", "EXPORT_DATA"]
}
{
"roleId": "rol_01933210-8b44-7c00-9e12-445566778899",
"accessMode": "SCOPED",
"scopedTemplateCount": 2,
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"updatedAt": "2026-11-15T23:35:02.000Z"
}
Related Documentation
-
Manage multi-workspace agency structures in Multi-Client Management.
-
Configure personal TOTP 2FA in Profile & Preferences.
-
Review audit log exports in Account Security & Access.
