Autenticação

As APIs da UY3 aceitam dois mecanismos de autenticação, escolhidos conforme o tipo de integração. Em ambos, a credencial vai no header de cada requisição — nunca em query string ou na URL.

1. JWT Bearer (AWS Cognito) — fluxos interativos e de backoffice

O padrão para usuários e para o backoffice. A identidade é gerida por um pool AWS Cognito; a API valida o token contra esse pool.

Header:

Authorization: Bearer <access_token_JWT>

Fluxo:

1. Autentique no Cognito com usuário e senha (fluxo SRP), no pool/região da UY3. Configuração de referência (identificadores públicos de SPA, mascarados aqui):

   {
     "Region": "us-east-2",
     "UserPoolId": "us-east-2_XXXXXXXXX",
     "ClientId": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
   }
   

2. Responda ao desafio de MFA (TOTP). O MFA é obrigatório e precisa já estar configurado no backoffice. O portal e as APIs não tratam NEW_PASSWORD_REQUIRED nem o setup inicial de MFA — esses fluxos são feitos no backoffice.

3. Receba o token (id/access token JWT) e envie-o no header Authorization: Bearer em todas as chamadas seguintes.

4. Renove antes de expirar. O JWT tem validade curta; ao expirar, refaça a autenticação (ou use o refresh token, quando disponível) para obter um novo. Requisições com token expirado retornam 401 Unauthorized.

2. ApiKey — integrações servidor-a-servidor

Para integrações máquina-a-máquina, quando o produto expõe esse modo. A chave é enviada em header próprio:

X-Api-Key: <sua_api_key>

Use ApiKey quando não há um usuário interativo no fluxo. Trate a chave como segredo: armazene em cofre, rotacione periodicamente e nunca a coloque em código-fonte, logs ou URLs.

Erros de autenticação e autorização

Segurança: escolha o mecanismo pelo tipo de integração — Bearer/Cognito para fluxos com usuário; ApiKey para servidor-a-servidor. Todo tráfego é HTTPS; credenciais só transitam em headers.