Como gerar uma API Key (cwo_live_*), definir escopos de acesso, restringir IPs e usar em chamadas HTTP. Inclui boas práticas de rotação e revogação.
O que é
API Key é uma credencial que sua aplicação ou ferramenta externa usa pra autenticar nas chamadas à API REST do Codewo (/api/v1/...). Cada chave:
- Tem escopo definido (o que ela pode ler/escrever).
- Pode ser limitada por IP.
- Tem prefixo público (visível) e segredo (visível só uma vez, na criação).
- Pode ser revogada a qualquer momento sem precisar mudar código de outras chaves.
Como criar
Em Configurações → Integrações → API Keys:
- Nova chave.
- Nome — Identificador interno, ex: "CRM HubSpot prod" ou "Dashboard Metabase".
- Escopos — Marque quais áreas a chave acessa:
channels:read— Listar canais.users:read— Listar membros.conversations:read— Listar e ler conversas.messages:read/messages:write— Ler e enviar mensagens.contacts:read/contacts:write/contacts:delete— CRUD de contatos.templates:read— Listar templates.plans:read/addons:read— Catálogo de planos (útil pra WL).
- IPs permitidos (opcional) — Lista de IPs ou faixas CIDR. Vazio = qualquer IP.
- Data de expiração (opcional) — Pra chaves temporárias.
- Salvar. O sistema mostra o token completo uma única vez — formato
cwo_live_xxxxxxxxxx.... Copie e guarde com segurança. Se perder, precisa criar outra (não dá pra recuperar).
Como usar
Em qualquer chamada HTTP, envie o token no header Authorization:
GET /api/v1/conversations
Host: codewo.com.br
Authorization: Bearer cwo_live_xxxxxxxxxx
Resposta de erro 401 = token inválido, revogado ou IP não permitido.
Documentação completa da API + tente direto: /api/docs (Scalar UI).
Listagem
A página de API Keys mostra:
- Prefixo — Primeiros chars do token (pra você identificar; cwo_live_AbC1d...).
- Últimos 4 caracteres.
- Escopos.
- IPs permitidos.
- Último uso — Quando a chave foi usada por último.
- Total de requests.
- Status (Ativa / Revogada / Expirada).
Revogação
Pra desativar uma chave imediatamente: clique no menu da chave → Revogar.
A partir desse momento, qualquer request com aquele token retorna 401. A revogação é permanente — a chave não pode ser reativada. Crie nova se precisar.
Pegadinhas comuns
- Token completo só aparece UMA vez. Se você não copiou no momento da criação, perdeu. Não tem como recuperar — só criar outra.
- Escopo mínimo. É fácil marcar tudo "por garantia" e expor mais que o necessário. Marque só o que sua integração precisa.
- IP whitelist é segurança extra forte. Se sua aplicação tem IP fixo, sempre use. Vazamento de token sem IP whitelist = qualquer um usa.
- Rotacionar é diferente de revogar. Rotação = criar nova chave, mudar nas aplicações, depois revogar a antiga (sem downtime). Revogação direta = aplicação para imediatamente.
- Sem suporte a token JWT. API Keys são opacas. Não tente "decodificar" — não é JWT.
- Rate limit por chave. Cada chave tem limite. Pra alto volume, considere múltiplas chaves ou cache de respostas no seu lado.
- Token em código-fonte é vulnerabilidade. Nunca commit em repo. Use variáveis de ambiente.
Boas práticas
- Uma chave por integração. "CRM HubSpot prod" + "CRM HubSpot staging" + "Dashboard Metabase" em chaves separadas. Quando uma integração quebra, só ela é afetada.
- Rotacione anualmente (no mínimo). Crie nova, troque nas apps, revogue antiga.
- Guarde em gerenciador de segredos — 1Password, Vault, AWS Secrets Manager. Não em planilha.
- Use IP whitelist sempre que possível. Sua aplicação roda em servidor com IP fixo? Adicione.
- Audite logs. Olhe "último uso" — chaves que não foram usadas em 6 meses provavelmente podem ser revogadas.
- Documente cada chave. Nome técnico vira óbvio em 1 mês; em 1 ano, ninguém lembra. Comentário em algum lugar.