# Autenticação com a chave de API

> Guarde a chave de API numa variável de ambiente, mande no cabeçalho X-ACCESS-TOKEN, reconheça o erro 401 e troque a chave sem parar as integrações.

Endereço: https://docs.nextags.com.br/comecar/autenticacao/
Tipo: Guia

Atualizado em: 26/10/2026

A API da NexTags reconhece a conta pela chave de API: cada chamada leva a chave no cabeçalho `X-ACCESS-TOKEN`. Neste guia, você guarda a chave fora do código, faz uma chamada autenticada, aprende a reconhecer o erro de chave e a trocar a chave quando precisar.

**Antes de começar**

- A chave de API da conta, gerada em **Configurações** › **Integrações** › **Chave de API do NexTags** › **Gerar**. O passo a passo com prints está em [Gerar a chave de API](https://help.nextags.com.br/tutoriais/configuracoes/chave-de-api/).
- Acesso de **Super Administrador**: só ele abre as **Configurações**. Veja [Administradores e permissões](https://help.nextags.com.br/tutoriais/configuracoes/administradores-e-permissoes/).
- Um servidor ou computador para rodar os exemplos, com cURL, Node 18 ou mais novo, Python 3 com `requests` ou PHP com a extensão cURL.

## Passo a passo

### Passo 1: Guarde a chave numa variável de ambiente

Guarde a chave numa variável de ambiente chamada `NEXTAGS_API_KEY`, na máquina que vai chamar a API. Assim a chave não fica escrita no código nem vai parar no Git.

**Guardar a chave**

```bash
export NEXTAGS_API_KEY="cole-aqui-a-chave"
```
```powershell
$env:NEXTAGS_API_KEY = "cole-aqui-a-chave"
```

Em produção, cadastre a variável no painel da hospedagem, do contêiner ou da função, ou no cofre de segredos que você usa. Todos os exemplos desta documentação leem a chave de `NEXTAGS_API_KEY`.

> **A chave age como a conta inteira:**
> A chave não tem permissões por área: com ela, dá para ler os contatos, enviar mensagens e mexer em etiquetas, pipelines, pedidos e agentes da conta. A conta tem uma chave só, a mesma no Zapier, no Make, no Pabbly, no n8n e no seu sistema. Por isso, a chamada sai sempre do servidor, nunca do navegador nem do app do celular: lá, qualquer pessoa veria a chave.

### Passo 2: Mande a chave no cabeçalho X-ACCESS-TOKEN

Em toda chamada, mande o cabeçalho `X-ACCESS-TOKEN` com a chave. Para testar, use [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta/), que só lê os dados da conta:

**Consultar a conta**

```bash
curl "https://app.nextagsai.com.br/api/accounts/me" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/accounts/me",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

Com a chave certa, a resposta é `200` com os dados da conta. Os campos estão em [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/).

### Passo 3: Reconheça o erro de chave

Sem a chave, com a chave incompleta ou com uma chave que foi excluída, a API responde `401`, em qualquer endereço, com este corpo:

```json
{"error": {"code": 401, "message": "No valid API key provided."}}
```

O cabeçalho `Content-Type` dessa resposta vem `text/html; charset=UTF-8`, mas o corpo é JSON. Leia o corpo como JSON sem confiar no cabeçalho. Trate o `401` como chave errada: repetir a chamada não resolve.

**Tratar o 401**

```bash
curl -i "https://app.nextagsai.com.br/api/accounts/me" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
// json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
const dados = await resposta.json();
if (resposta.status === 401) {
  throw new Error(`Chave de API recusada: ${dados.error.message}`);
}
console.log(dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/accounts/me",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
# json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
dados = resposta.json()
if resposta.status_code == 401:
    raise RuntimeError("Chave de API recusada: " + dados["error"]["message"])
print(dados)
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
// json_decode lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
$dados = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 401) {
    throw new RuntimeException('Chave de API recusada: ' . $dados['error']['message']);
}
print_r($dados);
```

### Passo 4: Troque a chave quando precisar

Troque a chave se ela vazou ou se alguém que a conhecia saiu da equipe. Em **Configurações** › **Integrações** › **Chave de API do NexTags**, clique em **Excluir** e depois em **Gerar**. A chave antiga para de valer: atualize a variável de ambiente e todas as ferramentas que usavam a antiga.

**Trocar a chave no servidor**

```bash
export NEXTAGS_API_KEY="cole-aqui-a-chave-nova"
```
```powershell
$env:NEXTAGS_API_KEY = "cole-aqui-a-chave-nova"
```

> **O Excluir não pede confirmação:**
> Entre o **Excluir** e o **Gerar**, a conta fica sem chave, e toda chamada recebe `401`. Deixe abertas as ferramentas que usam a chave (Zapier, Make, Pabbly, n8n, o seu sistema) e troque tudo de uma vez.

## Pronto: como conferir

- [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta/) responde `200`, com o `name` da sua conta.
- O cartão **Chave de API do NexTags** mostra o selo **Ativa**.

## Se não funcionou

### 401 com "No valid API key provided."

A chave não veio, veio incompleta ou foi excluída. Confira o nome do cabeçalho (`X-ACCESS-TOKEN`) e copie a chave inteira, sem espaços no começo ou no fim. Se a chave foi trocada, use a nova.

### O cliente HTTP diz que a resposta não é JSON

O erro de chave vem com `Content-Type: text/html`, mas o corpo é JSON. Leia o texto do corpo e converta para JSON você mesmo, sem depender do cabeçalho.

### A chamada funciona no meu computador e falha no servidor

A variável `NEXTAGS_API_KEY` não chegou ao processo do servidor. Cadastre a variável no painel da hospedagem, do contêiner ou da função e reinicie a aplicação.

### Não vejo a aba Integrações

Só **Super Administrador** abre as **Configurações**. Peça a um Super Administrador para gerar a chave e entregar por um canal seguro, como o cofre de senhas da equipe.

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Vou integrar o meu sistema à API da NexTags. Leia https://docs.nextags.com.br/comecar/autenticacao.md e https://docs.nextags.com.br/comecar/primeira-requisicao.md.

Meu sistema usa [linguagem e framework, por exemplo: Node 20 com Express]. Escreva um módulo cliente da API que lê a chave da variável de ambiente NEXTAGS_API_KEY, manda o cabeçalho X-ACCESS-TOKEN em toda chamada, lê o corpo como JSON mesmo quando o Content-Type vem text/html e lança um erro claro quando a resposta for 401. Não peça a minha chave.
```