Autenticação

A API usa OAuth2 no fluxo client_credentials — o padrão de mercado para integração máquina-a-máquina. Você troca suas credenciais por um token de acesso de curta duração e o envia em toda requisição.

Como obter credenciais

Suas credenciais (client_id e client_secret) são emitidas pela Socinal e amarradas ao seu parceiro_id. O client_secret é exibido uma única vez no momento da criação — guarde-o em local seguro. Para rotacionar, gere uma nova credencial, migre e revogue a antiga.

Nunca exponha o client_secret no front-end ou em apps cliente. Ele vive apenas no seu backend.

Trocando credenciais por um token

Solicite o token


curl -X POST https://econsignado-api.socinal.com.br/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_a1b2c3",
    "client_secret": "sk_live_..."
  }'

Receba o `access_token`


{
  "access_token": "eyJhbGciOiJ...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "margem:read emprestimos:read emprestimos:write"
}

O access_token é um JWT curto e sem refresh — ele carrega o seu parceiro_id e os escopos da credencial. Respeite o campo expires_in (em segundos) e solicite um novo token quando o atual expirar.

O campo scope traz os escopos concedidos à credencial separados por espaço (RFC 6749 §5.1) — leia-o para saber o que a credencial pode fazer, sem precisar decodificar o token. Dentro do JWT a mesma lista aparece no claim escopos (array); os dois são sempre equivalentes.

Use o token em todas as chamadas


curl https://econsignado-api.socinal.com.br/v1/linhas-credito \
  -H 'Authorization: Bearer eyJhbGciOiJ...'

Escopos

Cada credencial carrega um conjunto de escopos — os do campo scope da resposta do token. Uma chamada sem o escopo necessário retorna 403 ESCOPO_INSUFICIENTE.

Escopo	Permite
`margem:read`	Consultar margem, vínculos e autorizações no Dataprev
`simulacao:read`	Simular condições de crédito
`credito:read`	Listar linhas de crédito ativas
`fgts:read`	Consultar saldo e autorizações de FGTS
`propostas:read` / `propostas:write`	Ler / criar e operar propostas
`emprestimos:read` / `emprestimos:write`	Ler / criar e operar empréstimos
`documentos:read`	Baixar CCB e evidências de assinatura
`documentos:write`	Devolver pacote assinado externamente
`desembolso:write`	Mover dinheiro (PIX) — concedido com cautela
`refinanciamento:write`	Refinanciar empréstimo (emite nova CCB)
`renegociacao:write`	Renegociar empréstimo (emite nova CCB)
`repasses:read`	Consultar repasses e sua conciliação
`vinculos:read`	Consultar vínculos empregatícios e desligamentos
`escrituracao:read`	Consultar a escrituração do contrato
`webhooks:read` / `webhooks:write`	Listar / cadastrar e remover webhooks

Esta é a lista completa dos escopos desta API — a mesma publicada no securitySchemes do spec OpenAPI. Credenciais da API de Leilão carregam escopos leilao:*, que não valem nesta base URL.

A granularidade é proposital: um parceiro pode ter emprestimos:write mas não desembolso:write — ele origina a operação, e a Socinal libera o crédito.

Erros de autenticação

HTTP	`code`	Significado
401	`CREDENCIAL_INVALIDA`	Token ausente, inválido ou expirado
403	`ESCOPO_INSUFICIENTE`	A credencial não tem o escopo exigido pela rota
429	`RATE_LIMIT_EXCEDIDO`	Limite por credencial excedido — respeite o `Retry-After`