A API REST do Zenovay está documentada em docs.zenovay.com. Cada requisição se autentica com um token Bearer (uma «chave de API») que você gera no painel.
Informação
A API REST é um recurso pago. Está disponível nos planos Pro, Scale e Enterprise. No plano gratuito, você não pode criar ou usar chaves de API. Faça upgrade a partir de Configurações → Cobrança para desbloqueá-lo.
Como as chaves de API são organizadas
As chaves do Zenovay são pessoais: cada chave é criada por você e atua em seu nome, entre os times (espaços de trabalho) aos quais você escolhe dar a ela acesso. Você as gerencia em sua conta e elas são revogadas automaticamente quando você perde acesso a um time.
Ao criar uma chave, você decide duas coisas:
- Quais permissões ela tem — acesso completo, ou qualquer combinação de leitura, escrita e admin.
- Quais times ela pode alcançar — todos os times aos quais você pertence, ou um subconjunto específico.
Os proprietários e administradores do espaço de trabalho podem decidir quem pode criar chaves que alcancem o espaço de trabalho (todos os membros, apenas proprietários e administradores, ou ninguém). Essa governança fica na página da API do espaço de trabalho em Configurações → Segurança e acesso → Chaves de API.
Gerando uma chave de API
Abra as configurações de segurança da sua conta
No
app.zenovay.com, vá para Configurações → Conta → Segurança e acesso, depois encontre o cartão Chaves de API.Crie uma nova chave
Clique em Criar chave de API e dê a ela um nome que descreva a integração (ex.
Alertas Slack,Exportação interna de dados). Os nomes podem ter até 64 caracteres.Escolha as permissões
- Acesso completo — leitura e escrita em tudo o que a chave pode alcançar.
- Selecionar — escolha qualquer combinação de Leitura (endpoints GET de analytics), Escrita (POST/PATCH/DELETE) e Admin (endpoints somente para admin). Estes são independentes: uma chave somente leitura, um receptor de webhook somente escrita e uma chave de automação somente para admin são todas válidas.
O escopo Admin só pode direcionar times nos quais você é proprietário ou administrador.
Escolha o acesso do time
- Todos os times — a chave funciona em todos os times aos quais você pertence atualmente.
- Selecionar times — bloqueie a chave para times específicos. Ideal para restringir uma chave a um espaço de trabalho.
Copie a chave uma única vez
A chave começa com
zv_e é exibida apenas uma vez no momento da criação. Copie-a imediatamente para seu gerenciador de segredos. Armazenamos apenas um hash — não conseguimos recuperar uma chave perdida.
Requisição hello-world
Cada chamada à API envia a chave como token Bearer no cabeçalho Authorization.
curl https://api.zenovay.com/api/external/v1/websites \
-H "Authorization: Bearer zv_your_actual_key_here"
Uma resposta bem-sucedida retorna em JSON os sites aos quais a chave tem acesso. Se a chave for inválida ou estiver revogada, você receberá 401 Unauthorized. Se seu plano não incluir acesso à API, você receberá 403.
Limites de taxa
As requisições de API são limitadas por plano:
| Plano | Requisições por minuto |
|---|---|
| Free | Sem acesso a API |
| Pro | 30 |
| Scale | 60 |
| Enterprise | 120 |
As respostas incluem os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining, para que você possa lê-los e reduzir conforme se aproximar do limite. Veja Limites de taxa da API para detalhes.
Revogar chaves
- Revogar — abra a chave em Configurações → Conta → Segurança e acesso, depois escolha Revogar. A chave para de funcionar imediatamente.
- Editar — você pode renomear uma chave ou ajustar suas permissões e acesso ao time de lá.
- Auditoria — cada chave mostra quando foi criada. Se você não reconhecer uma chave ou não usar mais a integração por trás dela, revogue-a.
Para rotacionar uma chave, crie uma nova, implante-a, depois revogue a antiga.
Servidor MCP
O Zenovay também fala o Model Context Protocol, para que você possa conectar Claude Desktop, Cursor ou qualquer cliente MCP diretamente à sua analytics. MCP está disponível em todos os planos (Free, Pro, Scale e Enterprise), com limites de consultas diárias por plano. Não usa uma chave de API REST — em vez disso, você aponta seu cliente para https://api.zenovay.com/mcp e o autoriza uma vez via OAuth (sem chave para copiar). Você pode revisar e revogar clientes MCP conectados em Configurações → Conta → Segurança e acesso. Veja a documentação do MCP no site do desenvolvedor para a configuração completa e lista de ferramentas.
Boas práticas
- Nunca faça commit de uma chave em um repositório público. Armazene chaves em um gerenciador de segredos, não no controle de versão.
- Uma chave por integração. Se um fornecedor for comprometido, você só revoga sua chave.
- Use as permissões mais restritas que a integração precisa. Opte por somente leitura a menos que tenha que escrever.
- Restrinja por time para integrações que apenas tocam um espaço de trabalho, para que uma chave vazada não possa alcançar o resto.