Skip to content
Help Center Guide · Security & Compliance
3 min readVerified 2026-11-16

Account Security & Access

Protect operator accounts with role-enforced Two-Factor Authentication (2FA), password hygiene, session revocation, and key rotation.

In This Guide

Defense-in-Depth Identity & Access Architecture

Passinstance enforces multi-layered authentication, session isolation, and cryptographic key scoping across dashboard operators (/settings/workspace/security), enterprise SAML 2.0 single sign-on (SSO), server-to-server API integrations, and point-of-sale scanner devices.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
AUTHENTICATION & ACCESS CONTROL PIPELINE
STAGE 01
1
IDENTITY VERIFICATION
Dashboard Operators: Email/Password + TOTP 2FA OR Enterprise SAML 2.0 (/api/v1/auth/saml/:customerId/*)
Server Integrations: x-api-key (pi_live_... / pi_test_...) or OAuth2 JWT
Mobile Scanners: x-scanner-key + Operator PIN (/scanner-keys/unlock-pin)
STAGE 02
2
TENANT & RBAC AUTHORIZATION BOUNDARY
Workspace Security Policy (GET/PUT /customer/:customerId/security-settings)
Session Rotation on Workspace Switch (/organizations/current/workspaces/switch)
Fine-Grained Role & Template Scoping (/api/v1/rbac/roles)
STAGE 03
3
IMMUTABLE AUDIT LOGGING
Queries & CSV Export (GET/api/v1/audit-log & /api/v1/audit-log/export.csv)

Security Posture & Access Management Endpoints

Workspace owners and security administrators configure authentication policies (/settings/workspace/security), manage API keys (/settings/workspace/developer/api-credentials), and export compliance audit trails (/settings/workspace/developer/audit-logs) through these mounted endpoints:

Endpoint PathMethodAuthDescription
/api/v1/customer/:customerId/security-settingsGET / PUT / POST / DELETEBearerReads, updates (request payload), resets, or removes workspace security policy controls.
/api/v1/auth/saml/admin/:customerId/idpGET / PUT / DELETEBearerConfigures SAML Identity Provider metadata, Entity ID, and X.509 IdP certificates (GET .../setup for SP guide).
/api/v1/auth/saml/:customerId/loginGETPublicInitiates SP-SSO redirect (alongside GET .../metadata, POST .../acs, and GET /api/v1/auth/saml/resolve).
/api/v1/organizations/current/workspaces/switchPOSTBearerSwitches active tenant workspace and rotates session tokens to prevent cross-tenant replay.
/api/v1/api-keysGET / POSTBearerLists or provisions environment-bound API keys (pi_live_ on production, pi_test_ on sandbox).
/api/v1/api-keys/:id/regeneratePOSTBearerAtomically rotates an API key secret while preserving its UUID and configured scopes.
/api/v1/api-keys/:id/deactivatePOSTBearerImmediately suspends an API key without deleting historical usage telemetry.
/api/v1/audit-logGETBearerQueries immutable workspace security and administrative audit events (classifications up to SecurityLevel: `LOWMEDIUMHIGHCRITICAL`).
/api/v1/audit-log/export.csvGETBearer (audit:read-all)Streams up to 1000 filtered audit rows as text/csv for SOC 2 and compliance reviews.

Configuring Workspace Security Settings (request payload)

Administrators can enforce organization-wide Two-Factor Authentication, configure idle session timeouts, lock out brute-force logins, require password complexity, disable demo signing certificates, and control API key lifetimes via PUT /api/v1/customer/:customerId/security-settings:

JSON
{
  "requireTwoFactor": true,
  "enforceTwoFactorAuth": true,
  "sessionTimeoutMinutes": 60,
  "maxLoginAttempts": 5,
  "lockoutDurationMinutes": 15,
  "passwordMinLength": 12,
  "passwordRequireUppercase": true,
  "passwordRequireNumbers": true,
  "passwordHistoryLength": 5,
  "preventDemoCertificates": true,
  "apiRateLimitPerMinute": 120,
  "apiKeyExpirationDays": 180
}

Enterprise SAML 2.0 Single Sign-On (SAML Identity Provider)

Enterprise workspaces can federate operator logins with Okta, Microsoft Entra ID (Azure AD), Google Workspace, or Ping Identity via SAML SSO API (/api/v1/auth/saml/:customerId/*) and SAML Admin API (/api/v1/auth/saml/admin/:customerId/*). Each SAML Identity Provider record binds an identity provider Entity ID, SSO Sign-On URL, and X.509 signing certificate directly to the tenant domain.

Scoped API Key Lifecycle (API_KEY_SCOPE_VALUES & API_KEY_ENVIRONMENT_VALUES)

Passinstance enforces environment isolation (API_KEY_ENVIRONMENT_VALUES: 'live' | 'test') separating production credentials (pi_live_...) from sandbox keys (pi_test_...). When provisioning a key via POST /api/v1/api-keys, assign least-privilege scopes from API_KEY_SCOPE_VALUES:

  • 'passes' — Issue, update, void, and lookup pass instances.
  • 'templates' — Read template schemas, attributes, and mechanics.
  • 'scans' — Execute validation and mechanic redemptions.
  • 'webhooks' — Manage push/pull webhook subscriptions.
  • 'analytics' — Query workspace metrics and reports.
  • '*' — Full administrative developer API access (default if scopes is omitted).
JSON
{
  "name": "POS Checkout Integration — Production",
  "environment": "live",
  "scopes": ["passes", "scans"],
  "expiresAt": "2027-05-15T00:00:00.000Z"
}

Important: Raw API key secrets (data.key) and scanner pairing tokens (key) are returned only once at creation or rotation (POST /api/v1/api-keys/:id/regenerate). Store secrets in a dedicated vault or secrets manager and never embed pi_live_ keys in client-side browser bundles or mobile application binaries.

Review infrastructure encryption and compliance controls on the Security & Trust Center.

Related Product & Developer Documentation

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.