Autenticação
Proteja e gerencie as API keys usadas pela sua integração.
Todas as operações públicas usam uma API key no esquema Bearer:
Authorization: Bearer vsk_live_••••••••••••As chaves pertencem ao workspace que as criou. O tenant é derivado da chave autenticada; a API ignora qualquer tentativa de informar tenantId no payload.
Boas práticas
- Use uma chave por integração ou ambiente para facilitar rotação e auditoria.
- Armazene a chave somente no backend, em um secret manager.
- Nunca envie o segredo por query string.
- Revogue imediatamente uma chave exposta e atualize a integração.
- Não registre o header
Authorizationem logs ou ferramentas de observabilidade.
Respostas de autenticação
Uma chave ausente, inválida ou revogada produz 401 com um código estável:
{
"code": "API_KEY_INVALID",
"error": "Invalid API key"
}Um 403 indica que a chave foi reconhecida, mas o workspace não pode executar a operação naquele momento — por acesso, assinatura ou entitlement.
Scopes
Escolha as permissões mínimas ao criar a chave:
| Scope | Permissão |
|---|---|
messages:send | Enviar mensagens e consultar a entrega |
crm.contacts:read / crm.contacts:write | Ler ou alterar contatos |
crm.companies:read / crm.companies:write | Ler ou alterar empresas |
crm.deals:read / crm.deals:write | Ler ou alterar negócios |
crm.configuration:read | Ler pipelines, etapas, tags e campos personalizados |
webhooks:manage | Gerenciar endpoints de webhook de saída: criar, atualizar, excluir, regenerar segredo, testar e reenviar entregas |
Uma chave sem o scope exigido recebe 403 com o código API_KEY_SCOPE_REQUIRED.