Autenticação e Token de API

Para acessar a API, você precisa de uma API Key, criada no painel de gerenciamento. Todas as requisições à API devem incluir essa chave no cabeçalho de autenticação.

Como funciona

Cada API Key pertence a um único projeto e só acessa os recursos daquele projeto (chamadas, gravações, transcrições, pesquisas).
A chave é enviada no cabeçalho Authorization como um Bearer token.
Você pode criar quantas chaves quiser por projeto — o recomendado é uma chave por sistema integrado.

Criando uma API Key

Acesse o painel em app.videochamada.com.br e selecione o projeto desejado.
Abra a seção API Keys.
Clique em + Nova Chave. A chave é criada com um nome automático no formato Chave AAAA-MM-DD, que você pode editar para identificar o sistema que vai usá-la.
Copie o valor da chave e armazene-o em local seguro (por exemplo, um cofre de segredos da sua aplicação).

Na mesma tela você pode:

Visualizar chaves: consultar todas as chaves existentes, com data de criação e data de último uso (lastUsedAt).
Restringir por IP: configurar uma lista de IPs permitidos para cada chave (veja abaixo).
Excluir chaves: revogar chaves comprometidas ou não utilizadas.

Mantenha a chave em segredo

A API Key dá acesso direto aos recursos do projeto. Não a exponha em código de front-end, repositórios públicos ou logs. Se suspeitar de vazamento, exclua a chave imediatamente no painel — a revogação tem efeito imediato.

Cabeçalhos obrigatórios

Authorization: Bearer SUA_API_KEY
Content-Type: application/json

Testando a autenticação

A forma mais simples de validar sua chave é chamar GET /api/me:

curl -X GET "https://api.videochamada.com.br/api/me" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta esperada:

{
  "status": "ok"
}

Restrição por IP (opcional)

Cada chave pode ter uma lista de IPs permitidos, configurada no painel na própria chave. Quando a lista está preenchida:

Somente requisições vindas exatamente desses IPs são aceitas (comparação exata, sem faixas ou máscaras).
Requisições de qualquer outro IP recebem 401.

Quando usar

A restrição por IP é recomendada para integrações de servidor com IP fixo (por exemplo, um backend em nuvem com IP de saída estático). Evite usá-la se o seu sistema sai por IPs dinâmicos.

Falhas de autenticação

Status	Mensagem	Quando ocorre
401	`API key is missing`	O cabeçalho `Authorization` não foi enviado
401	`Invalid API key`	A chave é inválida ou foi excluída, ou a requisição veio de um IP fora da lista de IPs permitidos da chave

Exemplo de resposta de erro:

{
  "statusCode": 401,
  "timestamp": "2026-08-30T14:22:01.000Z",
  "path": "/api/calls",
  "message": "Invalid API key"
}

Melhorando a segurança

Revogação imediata: caso suspeite de uso indevido, exclua a chave imediatamente no painel. Ela para de funcionar na hora.
Uma chave por sistema: utilize chaves diferentes para sistemas ou equipes distintas — assim você revoga o acesso de um sistema sem afetar os demais.
Rotação periódica: crie uma chave nova, atualize seus sistemas e exclua a antiga.
Monitoramento: verifique regularmente a data de último uso de cada chave no painel para identificar chaves esquecidas ou acessos inesperados. Revogue as que não estiverem em uso.

Dica

Sempre que uma chave for excluída, atualize os sistemas que dependiam dela para evitar falhas de autenticação.