Skip to content
Guida del Centro assistenza · Sicurezza e conformità
4 min di letturaVerificato 2026-11-16

Sicurezza account e accessi

Proteggi gli accessi con 2FA per ruolo, rotazione chiavi API, revoca sessioni e blocco download con PIN.

In questa guida

Architettura di identità e accesso a difesa in profondità

Passinstance applica autenticazione multilivello, isolamento delle sessioni e limitazione crittografica degli ambiti delle chiavi per gli operatori della Dashboard (/settings/workspace/security), il Single Sign-On (SSO) aziendale tramite SAML 2.0, le integrazioni API server-to-server e i dispositivi scanner nei punti vendita.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI AUTENTICAZIONE E CONTROLLO ACCESSI
FASE 01
1
VERIFICA DELL'IDENTITÀ
Operatori Dashboard: Email/Password + 2FA TOTP OPPURE SAML 2.0 Enterprise (/api/v1/auth/saml/:customerId/*)
Integrazioni Server: x-api-key (pi_live_... / pi_test_...) o JWT OAuth2
Scanner Mobili: x-scanner-key + PIN Operatore (/scanner-keys/unlock-pin)
FASE 02
2
PERIMETRO DI AUTORIZZAZIONE TENANT E RBAC
Criteri di sicurezza workspace (GET/PUT /customer/:customerId/security-settings)
Rotazione sessione al cambio workspace (/organizations/current/workspaces/switch)
Ambito granulare per ruoli e modelli (/api/v1/rbac/roles)
FASE 03
3
REGISTRAZIONE DI AUDIT IMMUTABILE
Query ed esportazione CSV (GET/api/v1/audit-log e /api/v1/audit-log/export.csv)

Endpoint per la postura di sicurezza e la gestione degli accessi

I proprietari del workspace e gli amministratori della sicurezza configurano i criteri di autenticazione (/settings/workspace/security), gestiscono le chiavi API (/settings/workspace/developer/api-credentials) ed esportano i registri di controllo per la conformità (/settings/workspace/developer/audit-logs) tramite i seguenti endpoint montati:

Percorso EndpointMetodoAutenticazioneDescrizione
/api/v1/customer/:customerId/security-settingsGET / PUT / POST / DELETEBearerLegge, aggiorna (request payload), ripristina o rimuove i controlli dei criteri di sicurezza del workspace.
/api/v1/auth/saml/admin/:customerId/idpGET / PUT / DELETEBearerConfigura i metadati SAML Identity Provider, l'Entity ID e i certificati IdP X.509 (GET .../setup per la guida SP).
/api/v1/auth/saml/:customerId/loginGETPubblicoAvvia il reindirizzamento SP-SSO (insieme a GET .../metadata, POST .../acs e GET /api/v1/auth/saml/resolve).
/api/v1/organizations/current/workspaces/switchPOSTBearerCambia il workspace tenant attivo e ruota i token di sessione per prevenire attacchi di replay cross-tenant.
/api/v1/api-keysGET / POSTBearerElenca o genera chiavi API vincolate all'ambiente (pi_live_ in produzione, pi_test_ in sandbox).
/api/v1/api-keys/:id/regeneratePOSTBearerRuota in modo atomico il segreto di una chiave API preservandone l'UUID e gli ambiti configurati.
/api/v1/api-keys/:id/deactivatePOSTBearerSospende immediatamente una chiave API senza eliminare la telemetria storica di utilizzo.
/api/v1/audit-logGETBearerInterroga gli eventi di audit amministrativi e di sicurezza immutabili del workspace (classificazioni fino a SecurityLevel: `LOWMEDIUMHIGHCRITICAL`).
/api/v1/audit-log/export.csvGETBearer (audit:read-all)Trasmette fino a 1000 righe di audit filtrate in formato text/csv per revisioni SOC 2 e di conformità.

Configurazione delle impostazioni di sicurezza del workspace (request payload)

Gli amministratori possono imporre l'autenticazione a due fattori a livello di organizzazione, configurare i timeout per le sessioni inattive, bloccare i tentativi di accesso brute-force, richiedere la complessità delle password, disabilitare i certificati di firma demo e controllare la durata delle chiavi API tramite 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
}

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

I workspace Enterprise possono federare gli accessi degli operatori con Okta, Microsoft Entra ID (Azure AD), Google Workspace o Ping Identity tramite SAML SSO API (/api/v1/auth/saml/:customerId/*) e SAML Admin API (/api/v1/auth/saml/admin/:customerId/*). Ogni record SAML Identity Provider associa direttamente al dominio del tenant un Entity ID dell'identity provider, un URL di accesso SSO e un certificato di firma X.509.

Ciclo di vita delle chiavi API con ambito limitato (API_KEY_SCOPE_VALUES e API_KEY_ENVIRONMENT_VALUES)

Passinstance applica l'isolamento degli ambienti (API_KEY_ENVIRONMENT_VALUES: 'live' | 'test') separando le credenziali di produzione (pi_live_...) dalle chiavi sandbox (pi_test_...). Durante la generazione di una chiave tramite POST /api/v1/api-keys, assegni ambiti con privilegi minimi da API_KEY_SCOPE_VALUES:

  • 'passes' — Emette, aggiorna, annulla e ricerca le istanze di pass.
  • 'templates' — Legge gli schemi dei modelli, gli attributi e le meccaniche.
  • 'scans' — Esegue la convalida e i riscatti delle meccaniche.
  • 'webhooks' — Gestisce le sottoscrizioni webhook push e pull.
  • 'analytics' — Interroga le metriche e i report del workspace.
  • '*' — Accesso amministrativo completo alle API per sviluppatori (predefinito se scopes viene omesso).
JSON
{
  "name": "POS Checkout Integration — Production",
  "environment": "live",
  "scopes": ["passes", "scans"],
  "expiresAt": "2027-05-15T00:00:00.000Z"
}

Importante: I segreti in chiaro delle chiavi API (data.key) e i token di associazione dello scanner (key) vengono restituiti una sola volta al momento della creazione o della rotazione (POST /api/v1/api-keys/:id/regenerate). Conservi i segreti in un vault dedicato o in un gestore di segreti e non incorpori mai chiavi pi_live_ nei bundle del browser lato client o nei file binari delle applicazioni mobili.

Consulti i controlli di crittografia dell'infrastruttura e di conformità nel Centro sicurezza e fiducia.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.