Autenticação e API Keys
Como autenticar com API key, catálogo completo de escopos e compatibilidade de aliases.
Cada API key pertence a um workspace e define os escopos de acesso da integração.
Base URL
https://external-api.lip7.com.brComo autenticar
As três formas abaixo são aceitas (nesta ordem de resolução no servidor). O header x-api-key é o recomendado.
| Forma | Exemplo |
|---|---|
| Header recomendado | x-api-key: lip_... |
Bearer (somente se o token começa com lip_) | Authorization: Bearer lip_... |
| Query string | ?api_key=lip_... |
cURL
curl -X GET "https://external-api.lip7.com.br/api/external/v1/me" \
-H "x-api-key: lip_SUA_CHAVE"Nunca exponha a chave no front-end
A query string aparece em logs e referrers. Prefira x-api-key apenas no back-end.
Escopos (catálogo)
Formato: dominio:recurso:acao.
| Escopo | Permite |
|---|---|
* | Concede todos os escopos exceto os destrutivos de CRM (veja abaixo) |
usage:read | Consultar /me, status e logs de uso |
whatsapp:send | Enviar mensagens/templates; também mensagem em conversa |
whatsapp:templates:read | Listar/obter templates WhatsApp |
whatsapp:templates:write | Criar/editar/excluir templates WhatsApp |
whatsapp:campaigns:read | Listar/obter/analytics de campanhas WhatsApp |
whatsapp:campaigns:write | Criar/disparar/agendar/pausar/retomar/cancelar campanhas |
conversations:read | Listar e obter conversas |
conversations:write | Atualizar, assign, unassign, read, notes |
conversations:messages:read | Listar mensagens de uma conversa |
email:send | Envio transacional de e-mail |
email:templates:read | Templates e remetentes de e-mail |
email:campaigns:read | Listar/obter/analytics campanhas e-mail |
email:campaigns:write | Criar/disparar/agendar campanhas e-mail |
flows:read | Listar flows e execuções |
flows:trigger | Disparar flow e cancelar execução |
webhooks:manage | CRUD webhooks, deliveries, test, retry, rotate-secret |
media:write | Upload e obter mídia |
crm:contacts:read / write / delete | Contatos |
crm:companies:read / write / delete | Empresas |
crm:tags:read | Listar tags |
crm:members:read | Listar membros do workspace |
crm:segments:read / write | Segmentos |
crm:pipelines:read | Pipelines e stages |
crm:deals:read / write / delete | Negócios |
crm:activities:read / write | Atividades |
landing:pages:write | Sites, pages, themes, preview-tokens |
landing:ai:use | Geração/rewrite/chat de landing |
landing:publish | Publish, snapshots, rollback |
landing:domains:manage | Domínios |
Coringa * e deletes (ADR-002)
O coringa * não concede:
crm:contacts:deletecrm:deals:deletecrm:companies:delete
Esses escopos exigem grant explícito.
Compatibilidade
| Valor legado / compat | Equivale a |
|---|---|
conversations.view | conversations:read |
Key só com whatsapp:send | Também satisfaz usage:read (com log de aviso) |
Chave sem escopo
Uma chave criada sem escopos recebe * por padrão (sem deletes). Declare só o necessário.
Erros de auth
| HTTP | Situação |
|---|---|
401 | Key ausente, inválida ou expirada |
403 | Key válida sem escopo suficiente |