Autenticação em detalhe

Parâmetros de entrada

Parâmetro	Onde	Obrigatório	Descrição
x-api-key	header	Sim	Identifica a aplicação (Portal do Desenvolvedor)
context	header	Sim	Fixo: COBRANCA
Content-Type	header	Sim	Fixo: application/x-www-form-urlencoded
grant_type	body	Sim	password (login) ou refresh_token (renovação)
username	body	Para password	Código do Beneficiário (5) + Código da Cooperativa (4)
password	body	Para password	Código de acesso gerado no Internet Banking
refresh_token	body	Para refresh_token	Refresh token obtido na autenticação anterior
scope	body	Para password	Fixo: cobranca

Resposta

Campo	Descrição
access_token	Token JWT para autorizar as chamadas
token_type	Bearer
refresh_token	Usado para renovar sem reenviar username/password
expires_in	Expiração do access_token, em segundos (exemplo do manual: 300)
refresh_expires_in	Expiração do refresh_token, em segundos (exemplo do manual: 1800)
scope	Escopos do usuário (ex.: cobranca profile email)

Ciclo de vida do token, a regra que evita a maioria dos 401.

Primeira autenticação: grant_type=password, com username e password.
Reutilize o mesmo access_token em todas as chamadas até ele expirar. Não autentique a cada requisição.
Renovação: quando o access_token expirar, chame com grant_type=refresh_token e o refresh_token, sem enviar username/password.
Reautenticação: quando o refresh_token também expirar, volte ao passo 1.

Renovar o access_token com o refresh_token:

curl --location 'https://api-parceiro.sicredi.com.br/sb/auth/openapi/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-api-key: SEU_X_API_KEY' \
  --header 'context: COBRANCA' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=SEU_REFRESH_TOKEN'

⚠️
Os tempos de expiração podem variar entre Sandbox e Produção. Sempre leia expires_in e refresh_expires_in da resposta em vez de fixar 300/1800 no código.

Falhas comuns da autenticação

Status	Situação típica
400	grant_type ausente ou inválido
401	username/password inválidos, ou x-api-key ausente/inválido
404	URL de autenticação incorreta
504	Gateway Timeout — serviço não respondeu a tempo

(Sugestão de DX: incluir aqui um GIF curto mostrando a geração do código de acesso no Internet Banking e a obtenção do x-api-key no Portal, os dois pontos que mais geram dúvida.)