Skip to content
Help Center Guide · Account & Workspace Settings
3 min readVerified 2026-11-16

Team Members & Permissions

Invite colleagues, assign scoped Admin/Editor/Operator RBAC roles, restrict template/project access, and enforce 2FA per role.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
MULTI-LEVEL RBAC & TEMPLATE ACCESS SCOPING
STAGE 01 LEVEL 1: ORGANIZATION GOVERNANCE
Organization Roles: OWNER | ADMIN | MEMBER
Controls Multi-Workspace Provisioning, Consolidated Billing & SSO/SAML
STAGE 02 LEVEL 2: WORKSPACE ROLE HIERARCHY
Team Permissions API (/api/v1/rbac/roles)
System Roles: Workspace Admin, Campaign Editor, Scanner Operator
Custom Roles: POST/api/v1/rbac/roles with Granular Permission Scopes
Role Inheritance: GET/api/v1/rbac/roles/:roleId/inheritance
STAGE 03 LEVEL 3: TEMPLATE-LEVEL ACCESS SCOPING
POST/api/v1/rbac/roles/:roleId/template-access
Restricts Role Holders to Explicit templateId Allowlists
Enforced Server-Side Across Pass Search, Sendouts, Scans & Exports

Important: Authorization checks are enforced strictly server-side at the NestJS controller and service layers. Restricting a custom role via template-access guarantees 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 & RoleScopeCore Capabilities & Permissions
Organization OWNERAll Workspaces in OrganizationFull control over organization billing rollups (GET /api/v1/organizations/current/billing-summary), workspace creation/deletion, SAML 2.0 SSO configuration, and owner transfers.
Organization ADMINAssigned / All WorkspacesManage team invitations, workspace settings, Apple/Google signing certificates, API keys (api:keys-manage), and webhooks.
Workspace Editor (MEMBER)Single WorkspaceCreate and edit pass templates, configure mechanics and tiers, run CSV batch imports, and execute Delivery Center campaigns.
Workspace OperatorSingle Workspace / Scoped TemplatesIssue 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

EndpointHTTP VerbDescription
/api/v1/rbac/rolesGETLists all built-in and custom roles defined within the active workspace.
/api/v1/rbac/rolesPOSTCreates a custom RBAC role with explicit permission tokens and optional parent role inheritance.
/api/v1/rbac/roles/:roleIdPUTUpdates a custom role's name, description, requireTwoFactor policy, or permission set.
/api/v1/rbac/roles/:roleIdDELETEDeletes a custom role (fails safely if active team members are still assigned to the role).
/api/v1/rbac/roles/:roleId/inheritanceGETReturns the parent-child inheritance graph for the specified role.
/api/v1/rbac/roles/:roleId/inherited-permissionsGETComputes the effective union of direct permissions and permissions inherited from parent roles.
/api/v1/rbac/roles/:roleId/template-accessPOSTBinds the role to an explicit allowlist of templateIds (accessMode: 'SCOPED').

Creating a Custom Role with Inheritance

HTTP
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)

JSON
{
  "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:

HTTP
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"]
}
JSON
{
  "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"
}

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.