Autenticacao

Veridia usa autenticacao com bearer token. Cada request a API (exceto /health) precisa de um header Authorization:

Authorization: Bearer qv_pub_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9

Tipos de keys

Existem duas classes de keys, com diferentes propriedades de seguranca:

Tipo	Prefixo	Usar de	Permissoes
Publishable	qv_pub_*	Browser, widget, cliente publico	Iniciar verificacoes, enviar capturas
Secret	qv_sec_*	Apenas server-side	Todos os scopes publishable + obter veredictos + decriptar webhook secrets

A publishable key e segura para expor no seu HTML / SPA bundle. Esta atrelada a um tenant especifico e a uma lista de allowed origins — nao pode ser usada de um dominio que nao foi explicitamente whitelisted.

A secret key nunca e segura para expor. Pode obter veredictos para qualquer verificacao no seu tenant. Trate como uma password de banco de dados.

Environments

Cada tenant tem dois sets paralelos de keys:

Environment	Publishable	Secret	Comportamento
Test	qv_pub_test_*	qv_sec_test_*	Gratis, pipeline ML real, sem impacto no faturamento
Live	qv_pub_*	qv_sec_*	Faturamento real, verificacoes reais

Workflow recomendado:

1. Voce constroi e integra contra test keys
2. Roda verificacoes de teste ate ficar feliz com o fluxo
3. Muda para live keys em producao

As verificacoes de teste sao salvas no mesmo DB que as live, mas com um flag que as exclui do seu faturamento e estatisticas.

Whitelist de dominios (publishable keys)

Cada publishable key tem uma lista de allowed origins. O widget recusa carregar em qualquer dominio que nao esteja na lista.

Configure isto no seu dashboard em API keys → Edit → Allowed origins:

https://seuapp.com
https://staging.seuapp.com
http://localhost:3000

Wildcards como *.seuapp.com sao suportados.

:::warning Localhost durante desenvolvimento Voce deve adicionar explicitamente http://localhost:PORT aos allowed origins para testing local. O widget recusa por padrao — isso previne que keys vazadas sejam usadas por atacantes rodando seu proprio localhost. :::

Usando a secret key

Exemplos server-side:

curl

curl -X GET https://api.xxuxe.online/v1/verify/vf_AG07CDWRRFQV4T05ZXG2 \
  -H "Authorization: Bearer qv_sec_SEU_SECRET"

JavaScript / Node.js

const response = await fetch('https://api.xxuxe.online/v1/verify/' + id, {
  headers: {
    'Authorization': `Bearer ${process.env.VERIDIA_SECRET_KEY}`,
  },
});
const data = await response.json();

Python

import os, requests

response = requests.get(
    f"https://api.xxuxe.online/v1/verify/{verification_id}",
    headers={"Authorization": f"Bearer {os.environ['VERIDIA_SECRET_KEY']}"},
)
data = response.json()

PHP

<?php
$ch = curl_init("https://api.xxuxe.online/v1/verify/$verificationId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $_ENV['VERIDIA_SECRET_KEY'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Rotacao de keys

As keys podem ser rotadas a qualquer momento do dashboard:

1. Va a API keys
2. Clique em Rotate sobre a key que voce quer substituir
3. A nova key e mostrada uma vez — copie
4. Atualize seu codigo / environment
5. A key antiga continua funcionando por 15 minutos para te dar uma janela de deployment
6. Apos 15 minutos, a key antiga fica permanentemente invalida

Para revogacao de emergencia (suspeita de leak), use Revoke em vez disso — mata a key imediatamente.

Best practices

• Nunca commit secret keys ao source control. Use variaveis de ambiente ou um secrets manager
• Use keys separadas para test e live — nunca use uma live key em staging
• Limite os allowed origins apenas aos dominios que precisam
• Rotacione as keys trimestralmente como pratica de higiene
• Logue o request ID das responses da API — faz tickets de suporte resolverem 10x mais rapido
• Para chamadas server-side, sempre use a secret key — nunca a publishable

Erros de autenticacao

HTTP	Error code	O que significa
401	unauthorized	Header Authorization faltando ou malformado
401	invalid_key	A key nao existe, expirou, ou foi revogada
403	origin_not_allowed	Request de um dominio que nao esta em allowed origins
403	wrong_environment	Test key usada contra endpoint live ou vice-versa
429	rate_limited	Muitas requests — veja Rate limits

Veja Erros para o catalogo completo de erros.

Proximos passos

• POST /v1/verify/init — iniciar uma verificacao
• Erros — referencia completa de codigos de erro
• Rate limits — limites e quotas