Arquitetura de Identidade e Acesso com Defesa em Profundidade
O Passinstance impõe autenticação multicamada, isolamento de sessão e delimitação de âmbito de chaves criptográficas nos operadores do painel de controlo (/settings/workspace/security), autenticação única empresarial SAML 2.0 (SSO), integrações de API servidor-a-servidor e dispositivos de leitura no ponto de venda.
Endpoints de Postura de Segurança e Gestão de Acessos
Os proprietários de espaços de trabalho e os administradores de segurança configuram políticas de autenticação (/settings/workspace/security), gerem chaves de API (/settings/workspace/developer/api-credentials) e exportam registos de auditoria de conformidade (/settings/workspace/developer/audit-logs) através destes endpoints montados:
| Caminho do Endpoint | Método | Autenticação | Descrição | |||
|---|---|---|---|---|---|---|
/api/v1/customer/:customerId/security-settings | GET / PUT / POST / DELETE | Bearer | Lê, atualiza (request payload), repõe ou remove os controlos da política de segurança do espaço de trabalho. | |||
/api/v1/auth/saml/admin/:customerId/idp | GET / PUT / DELETE | Bearer | Configura metadados de SAML Identity Provider, Entity ID e certificados X.509 do IdP (GET .../setup para o guia do SP). | |||
/api/v1/auth/saml/:customerId/login | GET | Pública | Inicia o redirecionamento SP-SSO (juntamente com GET .../metadata, POST .../acs e GET /api/v1/auth/saml/resolve). | |||
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Alterna o espaço de trabalho ativo do tenant e roda os tokens de sessão para impedir ataques de repetição entre tenants. | |||
/api/v1/api-keys | GET / POST | Bearer | Lista ou aprovisiona chaves de API vinculadas ao ambiente (pi_live_ em produção, pi_test_ em sandbox). | |||
/api/v1/api-keys/:id/regenerate | POST | Bearer | Roda atomicamente o segredo de uma chave de API preservando o respetivo UUID e os âmbitos configurados. | |||
/api/v1/api-keys/:id/deactivate | POST | Bearer | Suspende imediatamente uma chave de API sem eliminar a telemetria histórica de utilização. | |||
/api/v1/audit-log | GET | Bearer | Consulta eventos imutáveis de auditoria administrativa e de segurança do espaço de trabalho (classificações até SecurityLevel: `LOW | MEDIUM | HIGH | CRITICAL`). |
/api/v1/audit-log/export.csv | GET | Bearer (audit:read-all) | Transmite até 1000 linhas de auditoria filtradas como text/csv para revisões SOC 2 e de conformidade. |
Configurar Definições de Segurança do Espaço de Trabalho (request payload)
Os administradores podem impor a Autenticação de Dois Fatores em toda a organização, configurar tempos limite de sessão inativa, bloquear tentativas de início de sessão por força bruta, exigir complexidade nas palavras-passe, desativar certificados de assinatura de demonstração e controlar o tempo de vida das chaves de API através de 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
}
Autenticação Única Empresarial SAML 2.0 (SAML Identity Provider)
Os espaços de trabalho empresariais podem federar inícios de sessão de operadores com Okta, Microsoft Entra ID (Azure AD), Google Workspace ou Ping Identity através de SAML SSO API (/api/v1/auth/saml/:customerId/*) e SAML Admin API (/api/v1/auth/saml/admin/:customerId/*). Cada registo SAML Identity Provider vincula diretamente um Entity ID do fornecedor de identidade, um URL de início de sessão SSO e um certificado de assinatura X.509 ao domínio do tenant.
Ciclo de Vida de Chaves de API com Âmbito Definido (API_KEY_SCOPE_VALUES e API_KEY_ENVIRONMENT_VALUES)
O Passinstance impõe isolamento de ambientes (API_KEY_ENVIRONMENT_VALUES: 'live' | 'test'), separando credenciais de produção (pi_live_...) das chaves de sandbox (pi_test_...). Ao aprovisionar uma chave através de POST /api/v1/api-keys, atribua âmbitos de menor privilégio a partir de API_KEY_SCOPE_VALUES:
-
'passes'— Emitir, atualizar, anular e consultar instâncias de passes. -
'templates'— Ler esquemas de modelos, atributos e mecânicas. -
'scans'— Executar validações e resgates de mecânicas. -
'webhooks'— Gerir subscrições de webhooks push/pull. -
'analytics'— Consultar métricas e relatórios do espaço de trabalho. -
'*'— Acesso administrativo total à API de programador (predefinição casoscopesseja omitido).
{
"name": "POS Checkout Integration — Production",
"environment": "live",
"scopes": ["passes", "scans"],
"expiresAt": "2027-05-15T00:00:00.000Z"
}
Importante: Os segredos brutos das chaves de API (
data.key) e os tokens de emparelhamento de leitores (key) são devolvidos apenas uma vez no momento da criação ou rotação (POST /api/v1/api-keys/:id/regenerate). Armazene os segredos num cofre dedicado ou gestor de segredos e nunca incorpore chavespi_live_em pacotes de navegador do lado do cliente ou em binários de aplicações móveis.
Consulte os controlos de encriptação de infraestrutura e conformidade no Centro de Segurança e Confiança.
