Para chamar a API da Autra, você precisa de credenciais (uma vez por tenant) e de um token JWT (renovado a cada hora). Esta página descreve, passo a passo, como obter ambos.

A autenticação usa o fluxo OAuth2 Client Credentials, com camada extra de criptografia RSA na entrega das credenciais.

Visão geral

Você (uma vez)         Autra
───────────            ─────
1. Gera par RSA  ────►
                       2. Recebe public key
3. Confirma posse ────►
   da private key      4. Verifica assinatura
                  ◄──── 5. Entrega client_id + client_secret
                        criptografados (RSA-OAEP)

A cada hora:
6. POST /oauth/token ──►
                  ◄──── 7. JWT Bearer (validade 1h)

A cada chamada de API:
8. Authorization: Bearer <JWT>

Pré-requisitos

Tenant ID fornecido pela Autra (chega por email após o cadastro).
IP de origem cadastrado na allowlist da Autra (peça via suporte).
Capacidade de gerar um par RSA 2048 (OpenSSL, biblioteca da linguagem, etc.).
Endpoint HTTPS para fazer chamadas (a API só aceita TLS).

Parte 1 — Setup (uma vez por tenant)

Esta parte você faz uma vez quando começa a integração. Depois, só renova o JWT (Parte 2).

Passo 1: Gere um par de chaves RSA

No seu lado, gere um par RSA 2048:

# Private key (guarde em local seguro)
openssl genrsa -out private.pem 2048

# Public key (vai ser enviada à Autra)
openssl rsa -in private.pem -pubout -out public.pem

⚠️ A private key nunca sai do seu servidor. Se vazar, gere um par novo e refaça os passos 2-4.

Passo 2: Envie a chave pública

POST /v1/tenants/{tenantId}/keys
Content-Type: application/json

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----"
}

Resposta 200:

{ "keyId": "key_a1b2c3d4..." }

✅ Guarde o keyId — ele identifica o par de chaves nesta integração.

Passo 3: Prove que você tem a private key

A Autra responde com um challenge (string aleatória). Você precisa assinar com sua private key e devolver:

POST /v1/tenants/{tenantId}/keys/{keyId}/verify
Content-Type: application/json

{
  "challenge":  "<challenge recebido>",
  "signature":  "<assinatura RSA-PSS SHA-256 base64>"
}

Resposta 200:

{ "verified": true }

✅ A partir daqui, a Autra confia que você é o dono da chave.

Passo 4: Gere as credenciais (client_id + client_secret)

POST /v1/tenants/{tenantId}/keys/{keyId}/credentials

Resposta 200:

{
  "encryptedClientId":     "<base64 RSA-OAEP>",
  "encryptedClientSecret": "<base64 RSA-OAEP>"
}

⚠️ As credenciais vêm criptografadas. Você precisa decifrar com sua private key usando RSA-OAEP (SHA-256):

echo "<encryptedClientId>" | base64 -d \
  | openssl pkeyutl -decrypt -inkey private.pem \
                     -pkeyopt rsa_padding_mode:oaep \
                     -pkeyopt rsa_oaep_md:sha256

✅ Guarde o client_id e client_secret decifrados em vault seguro. São o seu segredo permanente — não rotacionam automaticamente.

Parte 2 — Gerar token de acesso (a cada hora)

Com client_id + client_secret em mãos, gere um JWT a cada vez que precisar (ou cache por até 1h).

POST /v1/oauth/token
Content-Type: application/json

{
  "client_id":     "<seu client_id>",
  "client_secret": "<seu client_secret>",
  "grant_type":    "client_credentials"
}

Resposta 200:

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

✅ Cache o token por até 3600s. Não gere a cada request — o /oauth/token tem rate limit.

⚠️ Quando expirar (ou estiver perto), gere outro. Não há refresh token — é sempre uma nova chamada de /oauth/token.

Parte 3 — Usar o token em chamadas

Em todas as chamadas à API, inclua:

GET /v1/banking/accounts/{accountId}/limits
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

✅ Pronto. Você pode chamar qualquer endpoint da Autra.

Resumo dos mecanismos de segurança

Mecanismo	Descrição
Tenant ID	Identificador único por empresa (fornecido pela Autra)
OAuth2 Bearer Token	JWT HS256, validade de 1h
Allowlist de IP	Cada chamada precisa vir de um IP previamente autorizado
RSA-OAEP (SHA-256)	Credenciais entregues criptografadas com a sua chave pública
RSA-PSS (SHA-256)	Verificação de posse da private key no passo 3
TLS 1.2+	Toda a comunicação é via HTTPS

Erros comuns

HTTP	Causa	Solução
`401 invalid_client`	`client_id`/`client_secret` errados ou trocados	Cheque vault. Se persistir, regenere as credenciais (passo 4 do Setup).
`401 expired_token`	JWT passou de 1h	Gere outro via `/oauth/token`.
`403` (em qualquer rota)	IP não está na allowlist	Confirme com suporte qual IP a Autra está vendo.
`400` no `/keys/{keyId}/verify`	`signature` não bate com `challenge`	Cheque algoritmo (RSA-PSS SHA-256), encoding (base64) e que está usando a private key correta.
`400` ao decifrar credentials	Padding errado	Use RSA-OAEP com hash SHA-256. Não tente PKCS#1 v1.5.

Boas práticas

Cache o JWT por 3600s. Não gere a cada request — o /oauth/token tem rate limit.
Renove o JWT antes de expirar (margem de 60s) para evitar 401 no meio de um fluxo.
Nunca logue o client_secret ou o access_token. Mascare em logs e métricas.
Allowlist de IP por ambiente. Sandbox e produção têm IPs separados — não compartilhe credencial entre eles.
Rotacione a chave RSA a cada 6-12 meses. Para rotacionar: gere par novo, faça os passos 2-4, descarte a chave antiga.
Trate 401 como sinal de renovação: tente uma vez gerar outro JWT antes de propagar erro.

FAQ

Quanto dura o JWT? 3600 segundos (1 hora). Sem refresh token — é sempre uma nova chamada /oauth/token.

Posso gerar várias chaves RSA por tenant? Sim. Cada keyId é independente. Útil para ter chaves separadas por ambiente ou serviço.

Posso revogar uma chave? Hoje não há endpoint público de revogação. Para revogar, abra ticket no suporte com o keyId.

Os IPs da minha empresa mudaram. O que fazer? Peça atualização da allowlist no suporte. Sem isso, todas as chamadas voltam 403.

Posso usar o mesmo client_id em vários servidores? Pode, desde que todos os IPs estejam na allowlist. Mas recomendamos um par de credenciais por serviço/ambiente para auditoria mais fácil.

Por que RSA-OAEP e não JWE/JWA? Para minimizar dependências do lado cliente — RSA-OAEP é suportado em todas as linguagens via OpenSSL/lib padrão. JWE exigiria libs específicas.

Como sei qual IP a Autra está vendo? Tente uma chamada qualquer com o JWT e veja o 403 — ele inclui o IP detectado no body de erro.