> ## Documentation Index
> Fetch the complete documentation index at: https://docs.needalert.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Crie uma chave de API no painel e envie o token em toda requisição.

Toda requisição à API leva uma **chave de API** da sua rede. A chave é criada pelo **dono** da rede no painel, na tela **Integrações**, e identifica o sistema que chama a API (um ERP, uma loja virtual, uma agenda), não uma pessoa.

## Criar a chave

**1. Abra Integrações e clique em Nova chave**

Só o dono da rede vê **Integrações** no menu. Dê um **Nome** que identifique o sistema, como "ERP Loja Centro".

**2. Escolha as unidades**

**Todas as unidades, inclusive as futuras**, para o sistema central da rede, ou **Unidades escolhidas**, para um parceiro que atende só algumas lojas. Uma unidade fora da lista não existe para a chave: a API responde **404**.

**3. Marque as permissões**

Toda chave tem `view`. As demais seguem as permissões do painel (veja a tabela abaixo).

**4. Defina a expiração do token, se quiser**

**Expiração do token** é opcional. Um token expirado responde **401** até você emitir outro.

**5. Copie o token**

Ao clicar em **Criar chave**, o diálogo **Token da chave** mostra o token **uma única vez**. Copie-o para o cofre de segredos do seu sistema antes de clicar em **Concluído**. Se perder, emita um token novo e revogue o anterior.

| Permissão | O que libera na API |
| - | - |
| `view` | Ler unidades, itens, contagem de inscritos e disparos. Toda chave tem. |
| `create_items` | Criar itens. |
| `edit_items` | Editar, arquivar e trocar a foto de itens. |
| `dispatch_events` | Estimar, disparar, agendar, reagendar e cancelar alertas. Debita créditos como um disparo feito no painel. |
| `manage_billing` | Ler o saldo e o extrato de créditos. A compra de créditos fica só no painel. |

> [!WARNING]
>
> O token é um segredo de servidor. Nunca o coloque em código de navegador, de aplicativo ou em repositório. Quem tem o token age pela sua rede nas unidades da chave.

## Usar o token

Envie o token no header `Authorization` de toda requisição, e peça JSON em `Accept`:

```bash theme={null}
export API=https://needalert.app/api/v1
export TOKEN='3|na_...'

curl "$API/establishments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

O token tem a forma `<id>|na_...`. Envie-o inteiro, com a barra vertical.

## O que cada resposta significa

| HTTP | `code` | Causa |
| - | - | - |
| 401 | `unauthenticated` | Token ausente, malformado, expirado ou revogado. |
| 403 | `forbidden` | A chave não tem a permissão que a operação exige nesta unidade. |
| 403 | `tenant_suspended` | A rede dona da chave está suspensa. |
| 403 | `establishment_unavailable` | A unidade está inativa ou suspensa. |
| 404 | `not_found` | O recurso não existe ou está fora das unidades da chave. A API não revela se um recurso que você não pode ver existe. |

## Trocar o token sem parar o sistema

Uma chave aceita até **dois tokens ativos** ao mesmo tempo, para a troca não ter janela sem acesso.

**1. Emita o token novo**

Em **Integrações**, abra a chave (**Ver detalhes**) e clique em **Emitir token**. Copie-o: ele também aparece uma vez só.

**2. Atualize o seu sistema**

Troque o token no cofre de segredos e confirme que as chamadas continuam respondendo **200**.

**3. Revogue o token antigo**

Na tabela **Tokens**, use **Revogar token** no token antigo. O sistema que ainda o usasse perde o acesso na hora.

## Revogar a chave

**Revogar chave** derruba todos os tokens da chave na hora. A chave continua na lista como **Revogada**, para histórico, e não pode ser reativada: crie outra.

> [!NOTE]
>
> **Último uso** mostra a chamada mais recente entre os tokens ativos da chave. O uso de um token revogado deixa de contar, e um token recém-emitido só aparece depois da primeira chamada.

Veja também a página do painel: [Integrações](https://docs.needalert.app/establishments/integrations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.