Skip to content
Guía del Centro de ayuda · Seguridad y cumplimiento
4 min de lecturaVerificado 2026-11-16

Seguridad de cuenta y acceso

Refuerza cuentas mediante 2FA por rol, rotación de claves API, revocación de sesiones y bloqueo por PIN.

En esta guía

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.

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
PIPELINE DE AUTENTICACIÓN Y CONTROL DE ACCESO
ETAPA 01
1
VERIFICACIÓN DE IDENTIDAD
Operadores del Panel: Correo/Contraseña + TOTP 2FA O SAML 2.0 Empresarial (/api/v1/auth/saml/:customerId/*)
Integraciones de Servidor: x-api-key (pi_live_... / pi_test_...) o JWT
Escáneres Móviles: x-scanner-key + PIN de Operador (/scanner-keys/unlock-pin)
ETAPA 02
2
LÍMITE DE AUTORIZACIÓN DE INQUILINO Y RBAC
Política de Seguridad del Espacio (GET/PUT /customer/:customerId/security-settings)
Rotación de Sesión al Cambiar de Espacio (/organizations/current/workspaces/switch)
Delimitación Detallada de Roles y Plantillas (/api/v1/rbac/roles)
ETAPA 03
3
REGISTRO DE AUDITORÍA INMUTABLE
Consultas y Exportación CSV (GET/api/v1/audit-log y /api/v1/audit-log/export.csv)

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 EndpointMétodoAutenticaciónDescripción
/api/v1/customer/:customerId/security-settingsGET / PUT / POST / DELETEBearerLee, actualiza (request payload), restablece o elimina los controles de la política de seguridad del espacio de trabajo.
/api/v1/auth/saml/admin/:customerId/idpGET / PUT / DELETEBearerConfigura 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/loginGETPúblicoInicia la redirección SP-SSO (junto con GET .../metadata, POST .../acs y GET /api/v1/auth/saml/resolve).
/api/v1/organizations/current/workspaces/switchPOSTBearerCambia el espacio de trabajo activo del inquilino y rota los tokens de sesión para evitar la repetición entre inquilinos.
/api/v1/api-keysGET / POSTBearerLista o aprovisiona claves de API vinculadas al entorno (pi_live_ en producción, pi_test_ en sandbox).
/api/v1/api-keys/:id/regeneratePOSTBearerRota de forma atómica el secreto de una clave de API conservando su UUID y los alcances configurados.
/api/v1/api-keys/:id/deactivatePOSTBearerSuspende inmediatamente una clave de API sin eliminar la telemetría de uso histórica.
/api/v1/audit-logGETBearerConsulta eventos de auditoría administrativos y de seguridad inmutables del espacio de trabajo (clasificaciones hasta SecurityLevel: `LOWMEDIUMHIGHCRITICAL`).
/api/v1/audit-log/export.csvGETBearer (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:

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
}

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 omite scopes).
JSON
{
  "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 claves pi_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.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.