Autenticação da plataforma BaaS

Autenticação do integrador na plataforma BaaS: abrir contas, cadastrar webhooks da plataforma e listar contratos. Token obtido aqui não movimenta saldo, Pix nem boletos da conta.

Operações da conta após onboarding: Autenticação da conta BaaS. Scopes e variáveis: Sobre o BaaS.

Login (regras)

• Sem refresh token: ao expirar (expires_in, em geral 3600s), execute Login de novo.
• scope com todos os recursos necessários (onboarding, seller-webhooks, …). Scope em falta → 403 no endpoint mesmo com token válido.
• Após o Login, persista access_token no ambiente.
• hmac_secret em geral não vem no JSON do login, preencha {{hmac_secret}} no ambiente com o valor do onboarding Nuvende.

Assinatura HMAC (pedidos após o Login)

O pedido Login não usa HMAC, só Basic Auth + corpo OAuth.
Demais /api/v2/baas/* exigem Bearer e HMAC, exceto GET /api/v2/baas/status (só Bearer).

Sem HMAC válido: erro Invalid request signature, mesmo com token ok.

Variáveis

Conta titular: mesmo algoritmo; use Autenticação da conta BaaS.

Headers nos pedidos assinados

Authorization: Bearer {{access_token}}, X-Timestamp: {{timestamp}}, X-Nonce: {{nonce}}, X-Signature: {{signature}}, e Content-Type: application/json quando houver JSON.

Mensagem canônica (6 linhas, separadas por \n)

METHOD
PATH
QUERY
BODY
TIMESTAMP
NONCE

METHOD, GET, POST, PATCH, DELETE em maiúsculas.

PATH, caminho completo com /api/v2, ex. /api/v2/baas/balances. Sem host. Sem / final. IDs reais na URL, não placeholders.

QUERY, string após ?, ou vazio. Mesma ordem da URL.

BODY, bytes exatos do corpo. GET/DELETE assinados (regra usual): literal []. POST/PATCH: JSON idêntico ao enviado. Reenvio OTP: []. JSON: sem null omitido pelo gateway; sem pretty-print diferente do raw.

TIMESTAMP / NONCE, iguais aos headers X-*.

Assinatura: HMAC-SHA256(mensagem, hmac_secret) → hex em X-Signature (confirmar formato com Nuvende).

Fluxo de integração

1. Login, Basic Auth + corpo OAuth; persistir access_token; não enviar X-Timestamp, X-Nonce nem X-Signature.
2. Pedidos assinados, antes de cada chamada na plataforma BaaS ou na conta BaaS, gerar timestamp, nonce e signature.
3. Status, GET /api/v2/baas/status usa só Bearer (não calcular HMAC).

Geração da assinatura (referência)

1. Obter hmac_secret da configuração; abortar se vazio.
2. method = verbo HTTP em maiúsculas.
3. path = caminho completo com /api/v2 (sem host). Se for /api/v2/baas/status, não assinar.
4. query = string após ? na URL, ou vazio.
5. body = corpo bruto do pedido; em GET/DELETE assinados (regra usual), usar o literal [] quando não houver corpo.
6. timestamp = epoch UTC em segundos (string).
7. nonce = identificador único por pedido (ex.: UUID).
8. message = concatenar com \n: method, path, query, body, timestamp, nonce.
9. signature = HMAC-SHA256(message, hmac_secret) em hexadecimal → header X-Signature.

Erro de assinatura: conferir

hmac_secret do ambiente correto; PATH com /api/v2; QUERY igual à URL; BODY byte-a-byte ([] em GET se for a regra); timestamp/nonce iguais na mensagem e nos headers; token não expirado.

Ordem de teste

Login → hmac_secret → Status (só Bearer) → GET assinado na plataforma (ex.: listar propostas). Ordem completa: Sobre o BaaS.

Endpoints

Login {#login}

Contrato completo: Referência API, Login.

Pedido

Autenticação

• Basic Auth: {{client_id}} / {{client_secret}}
• Não use Authorization: Bearer neste pedido.
• Não envie X-Timestamp, X-Nonce nem X-Signature.

Corpo (application/x-www-form-urlencoded)

Resposta

hmac_secret costuma não vir no JSON, use o valor do ambiente.

Regras de negócio

• Apenas client_credentials (M2M).
• Sem refresh token: novo Login ao expirar.
• Scopes incompletos → 403 nos endpoints, mesmo com login 200.
• Credenciais da plataforma BaaS, não servem em Autenticação da conta BaaS.
• Após o login, pedidos da plataforma em /api/v2/baas/* (exceto Status) precisam de Bearer + HMAC.

Exemplo cURL

curl --request POST \
  --url "{{base_url}}/api/v2/auth/login" \
  --user "{{client_id}}:{{client_secret}}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=baas.onboarding-proposals.read baas.onboarding-proposals.write baas.onboarding-natural-persons.read baas.onboarding-natural-persons.write baas.onboarding-legal-persons.read baas.onboarding-legal-persons.write baas.contracts.read baas.seller-webhooks.read baas.seller-webhooks.write'

Corpo (application/x-www-form-urlencoded)

Resposta 200: OK

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