Skip to content
Guia da Central de Ajuda · Segurança e conformidade
4 min de leituraVerificado 2026-11-16

Segurança da conta e acessos

Proteja o acesso com 2FA por função, rotação de chaves API, revogação de sessões e bloqueio por PIN.

Neste guia

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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE AUTENTICAÇÃO E CONTROLO DE ACESSO
ETAPA 01
1
VERIFICAÇÃO DE IDENTIDADE
Operadores do Painel: E-mail/Palavra-passe + 2FA TOTP OU SAML 2.0 Empresarial (/api/v1/auth/saml/:customerId/*)
Integrações de Servidor: x-api-key (pi_live_... / pi_test_...) ou JWT
Leitores Móveis: x-scanner-key + PIN de Operador (/scanner-keys/unlock-pin)
ETAPA 02
2
FRONTEIRA DE AUTORIZAÇÃO DE TENANT E RBAC
Política de Segurança do Espaço de Trabalho (GET/PUT /customer/:customerId/security-settings)
Rotação de Sessão na Mudança de Espaço de Trabalho (/organizations/current/workspaces/switch)
Delimitação Fina de Função e Modelo (/api/v1/rbac/roles)
ETAPA 03
3
REGISTO DE AUDITORIA IMUTÁVEL
Consultas e Exportação CSV (GET/api/v1/audit-log & /api/v1/audit-log/export.csv)

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 EndpointMétodoAutenticaçãoDescrição
/api/v1/customer/:customerId/security-settingsGET / PUT / POST / DELETEBearerLê, 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/idpGET / PUT / DELETEBearerConfigura 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/loginGETPúblicaInicia o redirecionamento SP-SSO (juntamente com GET .../metadata, POST .../acs e GET /api/v1/auth/saml/resolve).
/api/v1/organizations/current/workspaces/switchPOSTBearerAlterna 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-keysGET / POSTBearerLista ou aprovisiona chaves de API vinculadas ao ambiente (pi_live_ em produção, pi_test_ em sandbox).
/api/v1/api-keys/:id/regeneratePOSTBearerRoda atomicamente o segredo de uma chave de API preservando o respetivo UUID e os âmbitos configurados.
/api/v1/api-keys/:id/deactivatePOSTBearerSuspende imediatamente uma chave de API sem eliminar a telemetria histórica de utilização.
/api/v1/audit-logGETBearerConsulta eventos imutáveis de auditoria administrativa e de segurança do espaço de trabalho (classificações até SecurityLevel: `LOWMEDIUMHIGHCRITICAL`).
/api/v1/audit-log/export.csvGETBearer (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:

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
}

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 caso scopes seja omitido).
JSON
{
  "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 chaves pi_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.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.