Autenticação

A API Pública usa o fluxo OAuth 2.0 Client Credentials, padrão de mercado para comunicação entre sistemas. Seu programa troca um par client_id + client_secret por um token JWT de curta validade e usa esse token no header Authorization: Bearer ... de cada chamada.

Obter o token

cURL

curl -X POST \
  "https://auth.banqer.com.br/realms/SUA-EMPRESA/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiI...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "api.cobranca.financeiro.read api.cobranca.fichas.read ..."
}

Python

import os, requests
TENANT = os.environ["BANQER_TENANT"]                # ex: "acme"
CLIENT_ID = os.environ["BANQER_CLIENT_ID"]
CLIENT_SECRET = os.environ["BANQER_CLIENT_SECRET"]

r = requests.post(
    f"https://auth.banqer.com.br/realms/{TENANT}/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
    timeout=10,
)
r.raise_for_status()
access_token = r.json()["access_token"]

JavaScript

const TENANT = process.env.BANQER_TENANT;
const body = new URLSearchParams({
  grant_type: 'client_credentials',
  client_id: process.env.BANQER_CLIENT_ID,
  client_secret: process.env.BANQER_CLIENT_SECRET,
});
const res = await fetch(
  `https://auth.banqer.com.br/realms/${TENANT}/protocol/openid-connect/token`,
  { method: 'POST', body, headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
);
if (!res.ok) throw new Error(`Token request failed: ${res.status}`);
const { access_token } = await res.json();

Veja também os capítulos de exemplos por linguagem com a implementação completa em Java, C#, Go e outras.

Tempo de vida do token

O token tem validade de 5 minutos (expires_in: 300). Faça cache em memória e reuse até pouco antes de expirar. Não chame o endpoint de token a cada request: além de gerar latência, isso pode acionar limites de uso no provedor de identidade.

O padrão recomendado:

1. Pegue o token uma vez.
2. Use até expires_in * 0.8 (4 minutos) e renove proativamente.
3. Se receber 401 Unauthorized com WWW-Authenticate: Bearer error="invalid_token", descarte o cache, peça um token novo e tente a requisição uma única vez. Não retorne em loop.

A implementação real está nos exemplos por linguagem. Todos seguem essa mesma estrutura.

Limite no endpoint de token

A borda Cloudflare bloqueia o endpoint de token quando recebe mais de 5 requisições em 10 segundos a partir do mesmo IP. A resposta é HTTP 429 e o bloqueio dura 10 segundos. O cache em memória descrito acima mantém você bem abaixo desse limite.

Segurança das credenciais

Regra	Por quê
Nunca comite client_secret no repositório	Acesso instantâneo para quem clonar
Carregue de variável de ambiente ou cofre (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault)	Auditável e rotacionável
Não inclua o token em logs, traces ou URLs	Tokens em log viram credenciais persistidas
Não exponha client_secret no navegador	O fluxo Client Credentials é apenas backend-to-backend
Use HTTPS sempre	A API recusa HTTP em texto puro

Para uma rotação de segredo iniciada pelo gestor Banqer, seu sistema deve estar preparado para receber um novo client_secret pelo canal acordado e atualizar o cofre. O segredo anterior fica inválido no momento da rotação.

Estrutura do token (informativo)

O token é um JWT assinado em RS256 pelo provedor de identidade do Banqer (Keycloak). Os campos relevantes:

{
  "iss": "https://auth.banqer.com.br/realms/SUA-EMPRESA",
  "aud": ["api.cobranca.financeiro", "api.cobranca.fichas", "..."],
  "azp": "SEU_CLIENT_ID",
  "scope": "api.cobranca.financeiro.read api.cobranca.fichas.read ...",
  "exp": 1779938273,
  "iat": 1779937973
}

Você não precisa decodificar ou validar o token: o servidor faz isso a cada requisição. Mas, se quiser, pode validar a assinatura localmente usando a JWKS pública em https://auth.banqer.com.br/realms/SUA-EMPRESA/protocol/openid-connect/certs.

Próximo passo

Escopos e permissões: entender quais dados sua credencial pode ler.