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.
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 Path | Method | Auth | Description | |||
|---|---|---|---|---|---|---|
/api/v1/customer/:customerId/security-settings | GET / PUT / POST / DELETE | Bearer | Reads, updates (request payload), resets, or removes workspace security policy controls. | |||
/api/v1/auth/saml/admin/:customerId/idp | GET / PUT / DELETE | Bearer | Configures SAML Identity Provider metadata, Entity ID, and X.509 IdP certificates (GET .../setup for SP guide). | |||
/api/v1/auth/saml/:customerId/login | GET | Public | Initiates SP-SSO redirect (alongside GET .../metadata, POST .../acs, and GET /api/v1/auth/saml/resolve). | |||
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Switches active tenant workspace and rotates session tokens to prevent cross-tenant replay. | |||
/api/v1/api-keys | GET / POST | Bearer | Lists or provisions environment-bound API keys (pi_live_ on production, pi_test_ on sandbox). | |||
/api/v1/api-keys/:id/regenerate | POST | Bearer | Atomically rotates an API key secret while preserving its UUID and configured scopes. | |||
/api/v1/api-keys/:id/deactivate | POST | Bearer | Immediately suspends an API key without deleting historical usage telemetry. | |||
/api/v1/audit-log | GET | Bearer | Queries immutable workspace security and administrative audit events (classifications up to SecurityLevel: `LOW | MEDIUM | HIGH | CRITICAL`). |
/api/v1/audit-log/export.csv | GET | Bearer (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:
{
"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 ifscopesis omitted).
{
"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 embedpi_live_keys in client-side browser bundles or mobile application binaries.
Review infrastructure encryption and compliance controls on the Security & Trust Center.
