Autenticação

POST /oauth2/token · OAuth 2.0 · JWT

1. Modelo de autenticação

A IORQ adota OAuth 2.0 client_credentials sobre Amazon Cognito — o fluxo apropriado para integrações server-to-server. Não há usuário final no caminho, não há autorização explícita por consentimento. As credenciais identificam a aplicação cliente do integrador; as permissões e os fundos acessíveis são resolvidos pela IORQ a partir do client_id.

sequenceDiagram
    participant INT as Integrador
    participant AUTH as IORQ Auth (Cognito)
    participant API as IORQ API

    INT->>AUTH: POST /oauth2/token (client_id + client_secret)
    AUTH-->>INT: access_token (JWT, exp=1h)
    loop Por até 1h
        INT->>API: Chamada operacional (Bearer access_token)
        API-->>INT: Resposta
    end
    Note over INT,AUTH: Após expiração, repete o /oauth2/token

2. Obter um token

2.1 POST /oauth2/token

POST /oauth2/token · application/x-www-form-urlencoded

Parâmetros (form-encoded)

Exemplo:

curl -X POST 'https://auth.iorq.com.br/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

Resposta:

{
  "access_token": "eyJraWQiOiJyc2EtMjAyNiIsImFsZyI6IlJTMjU2In0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2.2 Usar o token

Inclua o token no header Authorization de toda chamada operacional. O prefixo Bearer é obrigatório (com espaço). Lembre que as rotas operacionais ficam sob o prefixo /api.

curl 'https://hs-receiver-app-production.iorq.com.br/api/loan/?originator_proposal_code=OP-001' \
  -H 'Authorization: Bearer eyJraWQiOiJyc2EtMjAyNiIs...'

3. Ciclo de vida do token

• Validade: 1 hora (expires_in: 3600). O claim exp dentro do JWT é a fonte da verdade — use-o para programar renovação proativa.
• Renovação: não há refresh token. Para renovar, basta chamar POST /oauth2/token novamente com as mesmas credenciais.
• Revogação: não há endpoint público. Em caso de comprometimento, contate a IORQ para revogar o client_secret — o token deixa de ser aceito imediatamente.
• Múltiplos tokens válidos: permitido. Você pode emitir tokens em paralelo para escalar — não há limite enforced por essa via.

📘

Padrão recomendado

Mantenha um cache em memória do token e renove proativamente quando faltar menos de 5 minutos para expirar. Isso evita uma rajada de 401 quando o token expira no meio de um lote de cessões.

4. Anatomia do JWT

O access_token é um JWT (RFC 7519) emitido e assinado (RS256) pelo Amazon Cognito. A chave pública fica no JWKS do user pool Cognito:

https://cognito-idp.us-east-1.amazonaws.com/USER_POOL_ID/.well-known/jwks.json

Claims relevantes

📘

Partner e fundos não vêm no token

O parceiro (id_partner) e os fundos/credit vehicles acessíveis não são claims do JWT. Eles são resolvidos pela IORQ a cada chamada, a partir do client_id, pelo serviço de autorização (Cerberus). Você não precisa verificar a assinatura do token — a IORQ valida do lado dela.

5. Segurança do client_secret

• Armazene o client_secret em cofre de credenciais (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). Nunca em repositório, build artifact ou variável de ambiente em plain text.
• Rotacione o secret pelo menos a cada 12 meses. Em caso de qualquer suspeita, rotacione imediatamente — a IORQ emite secrets sob demanda.
• Não use o secret no frontend. O fluxo client_credentials é exclusivamente server-side.
• Restrinja o acesso ao secret aos serviços que efetivamente chamam /oauth2/token. Cada serviço que precisa de token deve ter sua própria credencial.

6. Erros de autenticação

7. Próximos passos