POST/api/v2/auth/login

Login

Autentica com Basic Auth e retorna um Bearer token para as demais rotas /api/v2/*.

Basic Auth

Combine client_id e client_secret como client_id:client_secret, codifique em Base64 e envie:

Authorization: Basic <base64(client_id:client_secret)>

Use placeholders {{clientId}} e {{clientSecret}} nos exemplos; não publique segredos reais.

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

ParâmetroObrigatórioDescrição
grant_typeSimValor fixo: client_credentials.
scopeSimScopes separados por espaço. O token recebe a interseção entre o solicitado, o cadastrado e o vinculado à aplicação.

Resposta (200)

CampoTipoDescrição
access_tokenstringToken para Authorization: Bearer ....
token_typestringGeralmente Bearer.
expires_inintegerExpiração em segundos (tipicamente 3600).

Scopes frequentes

GrupoScopes
Cobranças Pixcob.read, cob.write
Pagamentos Pixpix.read, pix.write
Contacontas.read, contas.saldo.read, contas.extrato.read, contas.chaves.read
Webhookswebhooks.read, webhooks.write
KYCkyc.background-check.natural-person, kyc.background-check.legal-person

Lista completa e regras de interseção: Referência login. Guia: Autenticação.

Exemplos cURL e SDK: aba Examples desta operação.

Parâmetros

Content-TypeObrigatório
header

Formato do corpo da requisição. Use `application/x-www-form-urlencoded`.

Tipo:string
Exemplo:
"application/x-www-form-urlencoded"

Autenticação

Esta requisição utiliza Basic Authentication no cabeçalho Authorization. As credenciais devem ser enviadas da seguinte forma:

  • clientId e clientSecret devem ser combinados no formato clientId:clientSecret
  • Esta string deve ser codificada em Base64
  • O cabeçalho deve ser: Authorization: Basic <base64(clientId:clientSecret)>

Exemplo:

  • Se clientId = "meu_client_id" e clientSecret = "minha_secret"
  • A string seria: "meu_client_id:minha_secret"
  • Após codificação Base64: "bWV1X2NsaWVudF9pZDptaW5oYV9zZWNyZXQ="
  • O cabeçalho final: Authorization: Basic bWV1X2NsaWVudF9pZDptaW5oYV9zZWNyZXQ=

Parâmetros do Corpo (x-www-form-urlencoded)

ParâmetroTipoDescrição
grant_typestringDeve ser "client_credentials"
scopestringLista de permissões separadas por espaço

Descrição dos Campos da Resposta

CampoTipoDescrição
access_tokenstringToken de acesso para autenticação nas demais requisições
token_typestringTipo do token, geralmente Bearer
expires_inintTempo de expiração do token em segundos (tipicamente 3600)

Este token deve ser utilizado no cabeçalho Authorization nas requisições subsequentes.

Scopes Disponíveis

Os scopes definem os níveis de permissão concedidos ao token de acesso. Abaixo está uma descrição dos principais scopes suportados pela API.

1. KYC (Know Your Customer) - Verificação de Identidade

ScopeDescrição
kyc.background-check.natural-personPermite verificar antecedentes de uma pessoa física.
kyc.background-check.legal-personPermite verificar antecedentes de uma pessoa jurídica.

2. Cobranças e Pagamentos Pix

ScopeDescrição
cob.writePermite criar novas cobranças (recebimento).
cob.readPermite visualizar cobranças existentes.
pix.writePermite iniciar e confirmar pagamentos Pix (envio).
pix.readPermite listar pagamentos Pix.

3. Conta (Mundo Digital)

ScopeDescrição
contas.readConsultar dados da conta.
contas.saldo.readConsultar saldo.
contas.extrato.readConsultar extrato.
contas.chaves.readListar chaves Pix da conta.

4. Webhooks

ScopeDescrição
webhooks.readPermite listar webhooks cadastrados.
webhooks.writePermite criar e gerenciar webhooks.

5. Merchants (Comerciantes)

ScopeDescrição
merchants.readPermite consultar informações de comerciantes.
merchants.writePermite cadastrar e atualizar comerciantes.

6. Terminais de Pagamento

ScopeDescrição
terminals.readPermite listar terminais de pagamento.
terminals.writePermite cadastrar e gerenciar terminais.

7. Transações

ScopeDescrição
transactions.readPermite consultar transações realizadas.
transactions.writePermite iniciar transações e criar ou atualizar documentos de comprovante (/api/v2/pagamentos/documents/...). Não existe scope documents.*.

Uso de Scopes

Os scopes devem ser enviados no parâmetro scope da requisição de autenticação, separados por espaço. O token final contém apenas a interseção entre: scopes solicitados, scopes cadastrados e scopes vinculados à aplicação. Scopes desconhecidos ou não concedidos são descartados (não geram erro no login; a rota depois pode responder 403 Insufficient scope).

Use o nome webhooks.* (plural). Não documente dict.* (órfãos). Não use cobv.* na docs até esses scopes existirem na tabela e estiverem vinculados (hoje as rotas Cobv exigem cobv.read/cobv.write, mas o seeder ainda não os cria; limitação conhecida no ambiente).

Exemplo padrão (sandbox: Cobrança + PIX + Contas + KYC):

--data-urlencode 'scope=cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person'

Para Pagamentos via Terminais, acrescente merchants.read merchants.write terminals.read terminals.write transactions.read transactions.write. Documentos de comprovante (impressão POS) usam transactions.write; não há scope documents.* separado.

Guia: Autenticação.

curl --location 'https://api-h.nuvende.com.br/api/v2/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '{{ clientId }}:{{ clientSecret }}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person'
const axios = require("axios");
const qs = require("querystring");

const clientId = "{{ clientId }}";
const clientSecret = "{{ clientSecret }}";
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");

const data = qs.stringify({
  grant_type: "client_credentials",
  scope:
    "cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person",
});

axios({
  method: "post",
  url: "https://api-h.nuvende.com.br/api/v2/auth/login",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    Authorization: `Basic ${credentials}`,
  },
  data,
})
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error.response?.data || error.message));
import requests
import base64

url = "https://api-h.nuvende.com.br/api/v2/auth/login"
client_id = "{{ clientId }}"
client_secret = "{{ clientSecret }}"
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

payload = {
    "grant_type": "client_credentials",
    "scope": "cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person",
}

headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": f"Basic {credentials}",
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
<?php
$clientId = "{{ clientId }}";
$clientSecret = "{{ clientSecret }}";
$credentials = base64_encode("$clientId:$clientSecret");

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-h.nuvende.com.br/api/v2/auth/login",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=client_credentials&scope=cob.read%20cob.write%20webhooks.read%20webhooks.write%20pix.read%20pix.write%20contas.read%20contas.saldo.read%20contas.extrato.read%20contas.chaves.read%20kyc.background-check.natural-person%20kyc.background-check.legal-person",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/x-www-form-urlencoded",
    "Authorization: Basic " . $credentials,
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{
  "access_token": "{{access_token}}",
  "token_type": "Bearer",
  "expires_in": 3600
}
{
  "message": "Invalid token",
  "error": ["invalid_credentials"]
}
{
  "message": "Insufficient scope",
  "error": ["insufficient_scope"]
}

Scope ausente no login pode gerar 403 Insufficient scope na rota chamada depois.