Autenticação e Chaves de API

Pro Plano

Proteja seu acesso à API com chaves de API. Crie e gerencie chaves para suas integrações.

Informação

A API REST do Zenovay é um recurso pago. Você precisa de um plano Pro ou superior para criar e usar chaves de API. Equipes gratuitas ainda podem enviar eventos com o script de rastreamento, mas não podem chamar a API programática.

Métodos de Autenticação

Chaves de API (Principal)

Autentique-se usando o header X-API-Key (recomendado) ou o header Authorization: Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Ou usando autenticação Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

As chaves de API sempre começam com o prefixo zv_.

Criando Chaves de API

As chaves de API no Zenovay são chaves pessoais: cada solicitação é atribuída a você, o usuário que criou a chave.

Passo 1: Abra a seção de chaves de API

Acesse Configurações → Conta → Segurança e acesso (/settings/account/security)
Encontre o cartão Chaves de API pessoais
Clique em Nova chave de API

Página Configurações → Conta → Segurança e acesso mostrando o cartão Chaves de API pessoais com chaves existentes e o botão Nova chave de API — A página Segurança e acesso é onde você cria e gerencia suas chaves de API pessoais.

Passo 2: Configure a chave

O formulário de criação pede três coisas:

┌─────────────────────────────────────────────────────┐
│ Criar Chave de API                                  │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Nome da chave                                       │
│ [ Integração de Produção                  ]        │
│                                                     │
│ Permissões                                          │
│ ● Acesso completo                                   │
│ ○ Apenas permissões selecionadas…                   │
│     ☐ Ler  ☐ Escrever  ☐ Administrador             │
│                                                     │
│ Acesso à equipe                                     │
│ ● Todas as equipes a que você tem acesso            │
│ ○ Apenas equipes selecionadas…                      │
│                                                     │
│ [Cancelar] [Criar]                                  │
└─────────────────────────────────────────────────────┘

Permissões controla o que a chave pode fazer. Acesso completo concede todos os escopos; ou escolha escopos individuais (Ler, Escrever, Administrador). A API Externa é somente leitura hoje, então uma chave Ler é suficiente para análises.
Acesso à equipe controla quais espaços de trabalho a chave pode alcançar. Deixe em Todas as equipes a que você tem acesso, ou restrinja a equipes específicas.

Passo 3: Salve sua chave

Importante: a chave completa é exibida apenas uma vez. Copie-a antes de fechar a caixa de diálogo.

┌─────────────────────────────────────────────────────┐
│ Sua nova chave de API                               │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Esta chave de API não será visível no futuro.      │
│ Por favor, copie-a agora.                           │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [Copiar]                                            │
│                                                     │
└─────────────────────────────────────────────────────┘

Formato da Chave

Todas as chaves de API usam um único formato:

Prefixo: zv_
As chaves são armazenadas como hashes SHA-256 por segurança
A chave completa é exibida apenas uma vez no momento da criação

Não existe um tipo de chave de teste/sandbox separado. Para separar desenvolvimento e produção, crie múltiplas chaves com nomes descritivos.

Permissões da Chave

Quando você cria uma chave, escolhe suas permissões (escopos) e seu acesso à equipe.

Escopo	O que concede
Acesso completo	Cada escopo
Ler	Acesso somente leitura à API Externa
Escrever	Endpoints de escrita (`POST`/`PATCH`/`DELETE`)
Administrador	Endpoints somente para administradores (requer proprietário ou função de administrador na equipe)

A superfície da API Externa documentada abaixo é somente leitura hoje, então uma chave Ler (ou Acesso completo) é tudo que você precisa para análises. A ingestão de rastreamento não usa uma chave de API; ela usa o script de rastreamento.

A quais Endpoints as Chaves de API Podem Acessar

Categoria de Endpoint	Endpoints
Análises	GET /analytics/:websiteId (visão geral, visitantes, páginas, países, tecnologia)
Sites	GET /websites, GET /websites/:websiteId
Mapas de calor	GET /heatmaps/:websiteId/pages
Reprodução de Sessão	GET /replays/:websiteId/sessions
Grupos de Erro	GET /errors/:websiteId/groups
Uso	GET /usage

Restrições de Acesso à Equipe

Todas as equipes

Por padrão, uma chave pode alcançar cada equipe (espaço de trabalho) à qual sua conta pertence, e cada site dentro dessas equipes:

Configuração mais simples
Boa para ferramentas internas que leem em seus espaços de trabalho

Equipes selecionadas

Para limitar uma chave, escolha Apenas equipes selecionadas… e selecione as equipes que pode alcançar. A chave funciona então apenas para sites que pertencem a essas equipes.

Casos de Uso para Restrições

Cenário	Configuração
Chave para um único espaço de trabalho	Apenas equipes selecionadas (selecione essa equipe)
Painel interno em todos seus espaços de trabalho	Todas as equipes a que você tem acesso

Gerenciando Chaves

Ver Todas as Chaves

O cartão Chaves de API pessoais lista cada chave com seu escopo, prefixo mascarado e última hora de uso:

┌─────────────────────────────────────────────────────┐
│ Chaves de API pessoais            [+ Nova chave]   │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Produção      [Acesso completo]   zv_abc…          │
│ Dashboard     [Ler]               zv_def…          │
│ Cliente A     [Ler]               zv_ghi…          │
│                                                     │
└─────────────────────────────────────────────────────┘

Detalhes da Chave

Clique em uma chave para abrir sua visualização detalhada:

Nome, escopo e acesso à equipe
Timestamps de criação e último uso
Atividade do lado do servidor (contagens de eventos aceitos e eventos recentes para essa chave)

Editar uma Chave

Na visualização de detalhes, selecione Editar no menu (botão …) para renomear a chave ou alterar seus escopos e acesso à equipe, depois salve.

Revogar uma Chave

Se uma chave estiver comprometida ou não utilizada:

Abra a visualização detalhada da chave
No menu …, clique em Revogar
Confirme

A chave é invalidada imediatamente. Para substituir uma chave, revogue a anterior e crie uma nova.

Segurança da Chave

Melhores Práticas

Prática	Por quê
Usar variáveis de ambiente	Não codificar
Conceder o escopo e acesso à equipe mais estreito	Limitar o raio de impacto
Chaves separadas por integração	Isolar dev/prod e clientes
Revogar chaves não utilizadas	Reduzir exposição
Monitorar a visualização de atividade	Detectar anomalias

Variáveis de Ambiente

Armazene chaves com segurança:

# Arquivo .env (nunca faça commit!)
ZENOVAY_API_KEY=zv_abc123...

// Usar no código
const apiKey = process.env.ZENOVAY_API_KEY;

Rotação de Chaves

Zenovay não regenera uma chave no local. Para rotacionar:

Crie uma nova chave
Atualize suas aplicações para usá-la
Verifique que tudo funciona
Revogue a chave anterior

Usando Chaves de API

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

Solução de Problemas

A API retorna erros na forma { "error": { "message": "...", "code": "..." } }.

Chave de API faltante ou inválida

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Retorna 401. Verifique:

A chave está copiada corretamente, com o prefixo zv_
Sem espaços ou quebras de linha extras
A chave não foi deletada
Você a enviou como X-API-Key ou Authorization: Bearer

O plano não inclui acesso à API

{
  "error": {
    "message": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
    "code": "API_PAID_PLAN_REQUIRED"
  }
}

Retorna 403. A API Externa requer um plano Pro ou superior. Atualize seu espaço de trabalho, depois crie uma chave.

Proibido para este site

{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

Retorna 403. A chave não tem acesso ao site solicitado, porque o site pertence a uma equipe fora do acesso à equipe da chave. Use uma chave cujo acesso à equipe cubra esse site, ou amplie o acesso à equipe da chave.

Atividade e Uso

Abra a visualização detalhada de uma chave para ver sua atividade do lado do servidor: contagens de eventos aceitos (últimas 24 horas, últimos 7 dias e todo o tempo) e os eventos mais recentes atribuídos a essa chave. Isso é útil para confirmar que uma chave está ativa e detectar uso inesperado.