Autenticação
Last updated
A API usa uma chave enviada no cabeçalho Authorization de cada requisição. Com exceção de GET /health, todas as rotas de integração exigem autenticação e uma conta apta ao uso da API.
Requisitos da conta
- E-mail confirmado.
- Conta não suspensa.
- Acesso à API habilitado.
- Aceite da versão vigente dos Termos de Uso.
Saldo é necessário para admitir consultas que reservam crédito. A falta de saldo não impede, por si só, as leituras autenticadas do catálogo, das métricas ou de resultados existentes.
Emissão da chave
As chaves são criadas no portal, na área Chaves de API, mediante um nome de 1 a 80 caracteres após a remoção de espaços nas extremidades. O nome identifica a integração no painel; não substitui o segredo de autenticação.
O segredo possui o prefixo voa_, seguido de 64 caracteres hexadecimais minúsculos. O valor completo aparece somente na criação. As consultas posteriores ao painel exibem metadados, como nome, prefixo, situação e último uso, sem recuperar o segredo completo.
A emissão e a revogação são realizadas pelo portal autenticado. Não há endpoint público de emissão de chaves na API de consultas.
Cabeçalho obrigatório
Authorization: Bearer <API_KEY>
O formato aceito é Bearer seguido da chave completa, sem aspas ou espaços adicionais. A chave não deve ser enviada em parâmetros de URL, no corpo JSON nem como senha de autenticação básica.
curl 'https://api.verifica-online.com.br/datasets' \
--header 'Authorization: Bearer <API_KEY>'
O portal usa uma sessão de navegador. Essa sessão não substitui o cabeçalho Bearer nas rotas da API.
Vínculo entre chave e operação
A API associa cada consulta e lote à conta e à chave usadas na criação. A recuperação por GET /queries/{request_id} ou GET /batches/{request_id} exige a mesma chave, ainda ativa, além dos requisitos da conta.
Outra chave da mesma conta não concede acesso ao resultado por esses endpoints. Nessa situação, a resposta é 404, sem revelar a existência da operação. A mesma restrição se aplica à repetição idempotente de uma operação criada por outra chave.
As métricas são agregadas por conta e podem ser lidas por qualquer chave válida dessa conta. O histórico do portal usa a autorização da sessão da conta, respeitando a validade de acesso aos resultados.
Revogação e troca de credenciais
A revogação impede o uso da chave e não pode ser desfeita. Uma nova chave é necessária para operações futuras. A revogação não transfere operações anteriores para a nova chave.
Na troca planejada de credenciais, a recuperação de operações ainda necessárias deve ocorrer antes da revogação, dentro do prazo de acesso aos resultados. Em caso de suspeita de comprometimento, a revogação imediata tem prioridade, seguida da revisão do consumo e das operações realizadas.
A troca ou recuperação da senha do portal não revoga automaticamente as chaves de API. Sessões de navegador e chaves de integração têm ciclos de autenticação distintos.
Respostas de autenticação e autorização
| HTTP | Código | Situação |
|---|---|---|
401 |
invalid_api_key |
Cabeçalho ausente ou inválido, chave inexistente ou revogada. |
403 |
account_not_verified |
E-mail da conta não confirmado. |
403 |
account_suspended |
Conta suspensa. |
403 |
api_access_disabled |
Acesso à API desabilitado. |
403 |
terms_acceptance_required |
Aceite da versão vigente dos Termos pendente. |
{
"error": {
"code": "invalid_api_key",
"message": "Chave de API inválida ou revogada.",
"request_id": "e21c271b-2d03-4abc-a706-392358af49ab"
}
}
error.request_id identifica a requisição HTTP que falhou. Ele não é um identificador de consulta ou lote. Os demais códigos e os procedimentos de recuperação estão descritos em Erros.
Proteção da chave
Execute as chamadas em um servidor que proteja a chave. Não inclua chaves no JavaScript entregue ao navegador, em aplicativos distribuídos, repositórios, capturas de tela ou registros de execução.
Remova os cabeçalhos de autenticação dos logs. Você pode usar chaves distintas em ambientes e integrações independentes para identificar o uso e revogar cada acesso separadamente. Não compartilhe a chave com terceiros nem a inclua em solicitações de atendimento.
Suspeitas de uso indevido podem ser comunicadas pelo canal oficial de contato, com identificadores das operações envolvidas e sem envio de segredos.