Arquitectura de Identidad y Acceso de Defensa en Profundidad
Passinstance aplica autenticación multicapa, aislamiento de sesiones y delimitación de alcance de claves criptográficas para los operadores del panel (/settings/workspace/security), el inicio de sesión único (SSO) empresarial SAML 2.0, las integraciones de API de servidor a servidor y los dispositivos de escaneo en el punto de venta.
Endpoints de Postura de Seguridad y Gestión de Acceso
Los propietarios de espacios de trabajo y los administradores de seguridad configuran las políticas de autenticación (/settings/workspace/security), gestionan las claves de API (/settings/workspace/developer/api-credentials) y exportan los registros de auditoría de cumplimiento (/settings/workspace/developer/audit-logs) a través de estos endpoints montados:
| Ruta del Endpoint | Método | Autenticación | Descripción | |||
|---|---|---|---|---|---|---|
/api/v1/customer/:customerId/security-settings | GET / PUT / POST / DELETE | Bearer | Lee, actualiza (request payload), restablece o elimina los controles de la política de seguridad del espacio de trabajo. | |||
/api/v1/auth/saml/admin/:customerId/idp | GET / PUT / DELETE | Bearer | Configura los metadatos de SAML Identity Provider, el Entity ID y los certificados IdP X.509 (GET .../setup para la guía del SP). | |||
/api/v1/auth/saml/:customerId/login | GET | Público | Inicia la redirección SP-SSO (junto con GET .../metadata, POST .../acs y GET /api/v1/auth/saml/resolve). | |||
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Cambia el espacio de trabajo activo del inquilino y rota los tokens de sesión para evitar la repetición entre inquilinos. | |||
/api/v1/api-keys | GET / POST | Bearer | Lista o aprovisiona claves de API vinculadas al entorno (pi_live_ en producción, pi_test_ en sandbox). | |||
/api/v1/api-keys/:id/regenerate | POST | Bearer | Rota de forma atómica el secreto de una clave de API conservando su UUID y los alcances configurados. | |||
/api/v1/api-keys/:id/deactivate | POST | Bearer | Suspende inmediatamente una clave de API sin eliminar la telemetría de uso histórica. | |||
/api/v1/audit-log | GET | Bearer | Consulta eventos de auditoría administrativos y de seguridad inmutables del espacio de trabajo (clasificaciones hasta SecurityLevel: `LOW | MEDIUM | HIGH | CRITICAL`). |
/api/v1/audit-log/export.csv | GET | Bearer (audit:read-all) | Transmite hasta 1000 filas de auditoría filtradas como text/csv para revisiones de SOC 2 y cumplimiento. |
Configuración de los Ajustes de Seguridad del Espacio de Trabajo (request payload)
Los administradores pueden exigir la autenticación de dos factores en toda la organización, configurar tiempos de espera de sesión inactiva, bloquear intentos de inicio de sesión por fuerza bruta, exigir complejidad en las contraseñas, deshabilitar certificados de firma de demostración y controlar la vigencia de las claves de API mediante 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
}
Inicio de Sesión Único SAML 2.0 Empresarial (SAML Identity Provider)
Los espacios de trabajo empresariales pueden federar los inicios de sesión de los operadores con Okta, Microsoft Entra ID (Azure AD), Google Workspace o Ping Identity mediante SAML SSO API (/api/v1/auth/saml/:customerId/*) y SAML Admin API (/api/v1/auth/saml/admin/:customerId/*). Cada registro SAML Identity Provider vincula el Entity ID de un proveedor de identidad, la URL de inicio de sesión SSO y el certificado de firma X.509 directamente al dominio del inquilino.
Ciclo de Vida de Claves de API con Alcance Delimitado (API_KEY_SCOPE_VALUES y API_KEY_ENVIRONMENT_VALUES)
Passinstance aplica aislamiento de entornos (API_KEY_ENVIRONMENT_VALUES: 'live' | 'test') separando las credenciales de producción (pi_live_...) de las claves de sandbox (pi_test_...). Al aprovisionar una clave mediante POST /api/v1/api-keys, asigne alcances de privilegio mínimo de API_KEY_SCOPE_VALUES:
-
'passes'— Emitir, actualizar, anular y consultar instancias de pases. -
'templates'— Leer esquemas de plantillas, atributos y mecánicas. -
'scans'— Ejecutar validaciones y canjes de mecánicas. -
'webhooks'— Gestionar suscripciones de webhooks push y pull. -
'analytics'— Consultar métricas e informes del espacio de trabajo. -
'*'— Acceso administrativo completo a la API para desarrolladores (valor predeterminado si se omitescopes).
{
"name": "POS Checkout Integration — Production",
"environment": "live",
"scopes": ["passes", "scans"],
"expiresAt": "2027-05-15T00:00:00.000Z"
}
Importante: Los secretos sin procesar de las claves de API (
data.key) y los tokens de vinculación del escáner (key) se devuelven solo una vez en el momento de su creación o rotación (POST /api/v1/api-keys/:id/regenerate). Almacene los secretos en una bóveda dedicada o en un gestor de secretos y nunca incruste clavespi_live_en paquetes de navegador del lado del cliente ni en binarios de aplicaciones móviles.
Consulte los controles de cifrado de infraestructura y cumplimiento en el Centro de Seguridad y Confianza.
