User Roles & Permissions

NowToPrint authorization is not decided by a role name alone. The current model evaluates platform roles, organisation role templates, permissions, capability entitlements, and resource scope together through a 13-layer authorization stack.

The 13-Layer Authorization Stack

The contract defines the following 13 decision concerns. This is not measured evidence that every route executes 13 independent runtime checks. Relationship-based access and metered quota also include model-ready areas; the actual protected server boundary decides an operation.

┌─────────────────────────────────────────────────────────┐
│  Layer 1:  Authentication (BetterAuth + Firebase)       │
│  Layer 2:  Principal Status (active/suspended/banned)   │
│  Layer 3:  Tenant Boundary (organization isolation)     │
│  Layer 4:  Resource Scope (platform/org/profile/team)   │
│  Layer 5:  Role → Permission (RBAC)                     │
│  Layer 6:  Permission → Capability (mapping)            │
│  Layer 7:  Package Entitlement (capability status)      │
│  Layer 8:  Billing Contract (grant state)               │
│  Layer 9:  Targeting Override (pilot/founder bonus)     │
│  Layer 10: Release Gate (feature flag)                  │
│  Layer 11: Usage Quota (metered limits)                 │
│  Layer 12: Risk Control (configured policy)             │
│  Layer 13: Decision Audit (decision evidence)               │
└─────────────────────────────────────────────────────────┘

How Decisions Are Made

A request must pass all applicable layers to be allowed. If any layer denies access, the request is blocked and the reason is logged for audit. This provides defense-in-depth security while maintaining a clear audit trail.

Platform Roles

Platform roles control access to admin surfaces and system-wide operations. Ordinary users have no privileged platform role; a canonical assignment is separate from organization membership.

Administration Roles

Role	Risk	Description
Platform Owner (`platform_owner`)	🔴 Critical	Highest canonical platform authority
Security Admin (`security_admin`)	🔴 Critical	Security configuration, role and API key management

Operational Roles

Role	Risk	Description
Marketplace Ops (`marketplace_ops`)	🟠 High	Day-to-day marketplace operations, user and org management
Finance Admin (`finance_admin`)	🟠 High	Financial operations, payments, payouts, commissions
Entitlement Admin (`entitlement_admin`)	🟠 High	Package and capability management, rollout control
Pricing Admin (`pricing_admin`)	🟠 High	Pricing configuration and commission management
Support Admin (`support_admin`)	🟡 Medium	Read-only support access to users and organisations
Growth Admin (`growth_admin`)	🟡 Medium	Analytics and growth operations
Content Localization Admin (`content_localization_admin`)	🟡 Medium	Content and translation management

Data Management Roles

Role	Risk	Description
Master Data Steward (`master_data_steward`)	🟡 Medium	Canonical master data management, import/export
Master Data Approver (`master_data_approver`)	🟡 Medium	Separate master data approval
Standards Steward (`standards_steward`)	🟡 Medium	Standards and quality data management
Readonly Auditor (`readonly_auditor`)	🟢 Low	Compliance audit access — read-only

Note: Historical platform values admin, superadmin, and super_admin are migration inputs only and grant no runtime permissions. They cannot be selected for new platform assignments. The auditor role has a single spelling, readonly_auditor.

Organisation Role Templates

Organisation role templates generate permission sets within a workspace. The available templates depend on your organization type (buyer, supplier, broker/agency).

Buyer Organizations (Individual / Corporate Customer)

Role	Description	Key Permissions
Owner (`org_owner`)	Organization-scoped ownership and management	Applicable buyer role permissions
Admin (`org_admin`)	Manages org settings, members, and operations	Member management, settings, operations
Buyer Manager (`buyer_manager`)	Procurement lead — creates RFQs, manages quotes and orders	RFQ create, quote management, order lifecycle
Buyer Member (`buyer_member`)	Team member — creates RFQs, views own orders	RFQ create, own order view
Finance (`finance_member`)	Finance team — views billing, manages payments	Billing view, payment management
Viewer (`viewer`)	Read RFQs, received quotes and orders	View-only

Print Producer Organizations

Role	Description	Key Permissions
Owner (`producer_owner`)	Full production operations and business management	Applicable producer role permissions
Admin (`producer_admin`)	Operations manager — manages team and production	Full producer operations
Quote Manager (`quote_manager`)	Sales/estimating — handles incoming RFQs and quoting	View matching RFQs, create/manage quotes
Production Manager (`production_manager`)	Shop floor lead — manages orders and production status	Order management, production tracking
Sales Rep (`sales_rep`)	Sales coordination	Producer order view/manage and customer view
Finance (`producer_finance`)	Accounting — manages financial operations	Invoice/payment records and payout view
Viewer (`producer_viewer`)	Read matching RFQs, quotes and orders	View-only

Agency / Broker Organizations

Role	Description	Key Permissions
Owner (`agency_owner`)	Full agency operations and client management	Applicable agency role permissions
Admin (`agency_admin`)	Operations lead — manages team and workflows	Full agency operations
Buyer (`agency_buyer`)	Client manager — creates RFQs on behalf of clients	Client-facing buyer operations
Seller (`agency_seller`)	Vendor relations — manages supplier interactions	Quote management, production coordination
Finance (`agency_finance`)	Accounting — billing, payments, commissions	Financial operations

Permission and Capability Relationship

A role grants permissions. Many permissions map to capabilities. If the organisation package does not include the capability, the action can still be blocked.

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│   Role   │────▶│  Permission  │────▶│  Capability  │────▶│ Package  │
│          │     │              │     │              │     │ Status   │
└──────────┘     └──────────────┘     └──────────────┘     └──────────┘
                                                            ▼
                                              ┌──────────────────────┐
                                              │ live | locked |      │
                                              │ preview | pilot |    │
                                              │ coming_soon |        │
                                              │ contact_sales        │
                                              └──────────────────────┘

Example Permission	Capability	Notes
`rfq.create`	`marketplace.rfq.create`	Buyer RFQ creation
`producer.quote.create`	`supplier.quote.manual`	Supplier quote creation
`producer.order.manage`	`supplier.order.lifecycle.basic`	Supplier order operations
`admin.entitlements.manage`	Entitlement control plane	High-risk; approval and audit required
`admin.roles.manage`	IAM control plane	High-risk role-management permission

Use the Roles & Permissions admin page to preview whether a role template, resource, package, and action combination is allowed.

How Roles Are Assigned During Onboarding

Onboarding creates canonical owner bindings scoped to the organization:

Usage type	Owner role
Individual / corporate buyer	`org_owner`
Agency	`agency_owner`
Print producer	`producer_owner`

owner is a simple role template, not a promise that new memberships also store a retired owner membership role. Separate self-service material/equipment vendor registration is closed. A producer owner binding does not activate candidate production capabilities; current membership, organization role status and effective entitlement still apply.

Organization finance roles (finance_member, producer_finance, agency_finance) explicitly do not grant platform payment approval, refunds, payout release, role/entitlement administration or billing.manage. The role tables describe responsibility families, not unconditional authority to execute every financial action.

Control-Plane Governance

The 2025-2026 launch posture treats authorization policy as versioned product infrastructure, not admin UI copy. The shared AuthZ SSOT defines the decision chain, high-risk permissions, control-plane role boundaries, and review cadence used by the admin read model.

Control Area	Launch Rule
High-risk role, entitlement, finance and API-key powers	Review at least every 30 days
Standard organisation and platform access	Review at least every 90 days
Read-only auditor access	Review at least every 180 days
Break-glass elevation	Time-box to 24 hours or less
Policy changes	Keep in contract/code review with audit evidence
Decision logs	Keep allow/deny, override, package and release-gate decisions auditable

Preview access to the entitlement control plane can include auditors. Publish access must stay limited to full platform admins and explicit entitlement/pricing/security operators.

Inviting Members

Select the correct organization context and open Teams.
If permissions and seat policy allow it, choose Invite member.
Enter the email and select Admin, Operator, Finance or Viewer.
Send the invitation; preserve the same attempt when a result is uncertain.
The invitee accepts the pending invitation with the matching verified email.

Creating an invitation does not prove email delivery, and there is no universal seven-day lifetime guaranteed here. Owner is excluded from ordinary invitations. An organization invitation does not assign a platform role.

Changing a Member's Role

Teams shows role templates and memberships; it does not currently offer a generic member-row Change role menu. Use the separate Transfer ownership control for an eligible active member. The server verifies permissions, security and ownership conditions. Other role corrections belong in an authorized management flow.

The current launch configuration disables MFA and uses recent primary sign-in for reviewed sensitive business actions. This does not replace the permission or approval checks. Follow any reauthentication prompt; a session refresh does not renew credential authentication time.

Best Practices

Principle of least privilege: Grant only the role template users need
Regular audit: Review members, role changes, and entitlement changes periodically
Critical actions: Keep role, entitlement, API key, and finance changes behind approval and audit
Departing team members: Remove leavers immediately and revoke service accounts where applicable
Package separation: Remember that package entitlement is checked separately from user permission