Autenticação

POST /token · OAuth 2.0 · JWT

1. Modelo de autenticação

A IORQ adota OAuth 2.0 client_credentials — 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 e dão acesso ao conjunto de fundos provisionados para ela.

sequenceDiagram
    participant INT as Integrador
    participant AUTH as IORQ Auth
    participant API as IORQ API

    INT->>AUTH: POST /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 /token

2. Obter um token

2.1 POST /token

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

Parâmetros (form-encoded)

Exemplo:

curl -X POST 'https://auth-hs.iorq.com.br/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,
  "scope": "loan.write installment.write loan.read"
}

2.2 Usar o token

Inclua o token no header Authorization de toda chamada operacional. O prefixo Bearer é obrigatório (com espaço).

curl 'https://hs-api.iorq.com.br/loan/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 /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) assinado em RS256 pelo par de chaves da IORQ. A chave pública está disponível em:

https://auth-hs.iorq.com.br/.well-known/jwks.json

Claims relevantes

Você não precisa verificar a assinatura do token — a IORQ valida do lado dela. Mas se sua arquitetura precisar (ex: para repassar a outro serviço interno), use a JWKS.

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 /token. Cada serviço que precisa de token deve ter sua própria credencial.

6. Erros de autenticação

7. Próximos passos