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.

As duas formas são equivalentescurl

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.

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.

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.