---
title: "Autenticação"
slug: authentication
group: "Primeiros passos"
source: https://linkzap.orion.moe/developers/authentication
openapi: https://linkzap.orion.moe/openapi.json
---

# Autenticação

Uma chave, dois escopos, nenhum OAuth. Toda chamada leva a chave num cabeçalho.

## Como enviar a chave

O jeito preferido é `Authorization: Bearer`. Para ferramentas que não deixam mexer nesse cabeçalho (é o caso de vários construtores de automação), `x-api-key` vale o mesmo.

Comando — As duas formas são equivalentes:

```bash
curl https://linkzap.orion.moe/api/v1/me -H "Authorization: Bearer lz_SUA_CHAVE"

curl https://linkzap.orion.moe/api/v1/me -H "x-api-key: lz_SUA_CHAVE"
```

A chave tem sempre o formato `lz_` seguido de 40 caracteres. Qualquer outra coisa — chave truncada, com espaço, revogada ou de outra instalação — responde `401` com o motivo.

## Os dois escopos

- **Chave da conta** (Configurações → Integrações): alcança todos os números, todos os contatos e todas as conversas da organização. É a que você usa no seu próprio backend.
- **Chave de canal** (Canais → Copiar chave de API): só fala por aquele número. Pedir outro `channelId` responde `403`, e `GET /channels`, `GET /conversations` e `GET /messages` devolvem só o que é daquele canal. É a que você entrega a um integrador de fora.

> [!WARNING]
> **Contato é da conta, não do canal**
>
> A única exceção ao parágrafo acima, e ela é deliberada: `GET /contacts` e `POST /contacts` **não** filtram por canal. Um contato é a pessoa, e a mesma pessoa pode falar por mais de um número seu — uma base de contatos por canal criaria duplicata a cada número novo. Na prática: uma chave de canal lê e escreve **todos** os contatos da organização. Se isso não serve ao seu caso, não entregue uma chave de canal a terceiros esperando que ela isole a base.

Com uma chave de canal você pode **omitir** o `channelId` nas rotas de escrita: o escopo preenche sozinho. `GET /api/v1/me` diz qual dos dois você tem em mãos.

## Criar, rotacionar, revogar

A chave aparece **uma vez**. Guardamos apenas um hash dela — nem nós conseguimos lê-la de volta, o que também significa que ninguém com acesso ao banco consegue. A lista mostra só o prefixo (`lz_ab12cd34`), o nome que você deu e quando foi usada pela última vez.

- **Rotacionar** é criar a nova, trocar no seu sistema e só então revogar a antiga — nessa ordem, a integração não pisca.
- **Revogar** vale na hora, na chamada seguinte. Não há prazo de carência.
- Em **Canais → Copiar chave de API**, “copiar” _gera_ uma chave nova e revoga a anterior do mesmo canal — pela mesma razão: o valor antigo não existe mais em lugar nenhum para ser copiado de novo.

> [!CAUTION]
> **Se a chave vazou**
>
> Revogue primeiro, investigue depois. Em Configurações → Integrações, o campo “último uso” de cada chave mostra se ela andou sendo usada — e por onde continuar procurando.

## Onde a chave não deve estar

- **No navegador, nunca.** A API não responde a pedidos de outra origem (não há CORS), justamente para que ninguém seja tentado a chamá-la do JavaScript de uma página — ali a chave estaria à vista de qualquer visitante. Chame sempre do seu servidor.
- No repositório: variável de ambiente ou cofre de segredos, como as outras credenciais.
- Em log de erro e em rastro de exceção — é o vazamento mais comum, e o mais silencioso.