Começar

Autenticação

Toda requisição ao contrato /v1 leva a sua API key no header x-api-key. Não há login, não há token de sessão, não há refresh.

header

x-api-key: <sua-api-key>

Exemplo

bash

curl https://api.nuntis.com.br/v1/channels \
  -H "x-api-key: $NUNTIS_API_KEY"

Credencial em query string é recusada

Enviar a key como parâmetro de URL (?api_key=…) não funciona, e a recusa é por desenho. Query string vaza em três lugares que ninguém controla:

log de proxy e de servidor, onde a URL completa costuma ser gravada em texto puro;
histórico do navegador, se a URL passar por um;
o header Referer, que carrega a URL de origem para terceiros.

Header não vai para nenhum dos três por padrão. É a única forma aceita aqui.

O que a key delimita

A key é o escopo. Ela identifica o seu produto, e tudo que você lê ou escreve pertence a ele — números, conversas, mensagens, subscriptions de webhook.

Recurso de outro produto responde 404

Pedir um recurso que não é seu devolve 404 NOT_FOUND, exatamente igual a pedir um recurso que não existe. Os dois casos são indistinguíveis de propósito: um 403 confirmaria a existência do recurso alheio, e com identificadores adivinháveis isso viraria um enumerador da base de outro produto.

Uma key por produto, por ambiente

Não emita uma key por cliente final nem por operador. A separação entre os seus clientes é feita pelo modelo de recursos, não por credenciais — multiplicar keys só multiplica o que você precisa rotacionar quando uma vazar.

Guarde a key como segredo

Só no servidor. Nunca em aplicativo móvel, front-end web, repositório ou build de cliente — qualquer coisa que rode na máquina do usuário final é pública, mesmo compilada.
Em variável de ambiente (ou no cofre que você já usa), lida em tempo de execução. A key precisa ser trocável sem recompilar nada.
Fora dos logs. Se o seu cliente HTTP registra headers ao depurar, filtre x-api-key explicitamente.

javascript

// A key é lida do ambiente, nunca escrita no código.
const NUNTIS_URL = process.env.NUNTIS_URL;      // https://api.nuntis.com.br
const NUNTIS_API_KEY = process.env.NUNTIS_API_KEY;

async function nuntis(caminho, opcoes = {}) {
  const resposta = await fetch(`${NUNTIS_URL}/v1${caminho}`, {
    ...opcoes,
    headers: {
      'x-api-key': NUNTIS_API_KEY,
      'content-type': 'application/json',
      ...(opcoes.headers || {}),
    },
  });

  if (!resposta.ok) {
    // O corpo de erro é sempre { code, message, retryable, source }.
    const erro = await resposta.json();
    throw Object.assign(new Error(erro.message), erro);
  }

  return resposta.status === 204 ? null : resposta.json();
}

Rotação

Trocar a key é uma mudança de variável de ambiente, não de código. Se você suspeitar de vazamento, peça uma key nova e descarte a antiga — como toda chamada é autenticada por header, não há sessão pendurada para expirar.

Erros de autenticação

`code`	HTTP	Quando acontece
`UNAUTHORIZED`	401	Key ausente, inválida, expirada, sem permissão para a rota, ou enviada por um meio não aceito (por exemplo, query string).
`NOT_FOUND`	404	A key é válida, mas o recurso pedido não é do seu produto — ou não existe. Os dois são indistinguíveis.
`RATE_LIMITED`	429	Limite de requisições da key excedido. Respeite o header `Retry-After`.

A forma completa do corpo de erro e a lista inteira de códigos estão em Erros.

Enviar mensagens → Erros →