Autenticação

Toda requisição à API da Certivant é autenticada com uma chave de API — um token Bearer de longa duração, limitado a uma única organização. Sessões e cookies são usados no painel; a API nunca os utiliza.

Formato do cabeçalho

Authorization: Bearer ck_live_NjV3aXJWN0RpZ2tRZ1JLWEcxc1V2eEgwUjg...

• O nome do cabeçalho é Authorization.
• O esquema é Bearer (um espaço, seguido da chave).
• A chave começa com ck_live_ (produção) ou ck_test_ (teste). Chaves antigas que começam com kyk_ continuam funcionando sem alterações.

Toda resposta de um endpoint autenticado por chave traz X-Certivant-Environment: live|test. Chaves de teste apenas identificam o uso; elas não isolam os dados (veja Chaves de produção vs. de teste).

Se a chave estiver ausente, for desconhecida, tiver sido revogada, estiver expirada ou tiver sido substituída por rotação, a Certivant responde com HTTP 401 e error.code = "UNAUTHORIZED". error.reason é um subcódigo estável:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "api_key_expired",
    "message": "This API key has expired. Create or rotate a key."
  }
}

De onde vêm as chaves

As chaves de API são criadas no painel, em KYC → Desenvolvedor. Você precisa ser o proprietário (Owner) ou um administrador (Admin) da organização. A chave é exibida apenas uma vez, logo após a criação — a Certivant armazena um hash SHA-256, por isso não é possível exibi-la novamente. Se você perdê-la, revogue-a e crie uma nova.

O painel lista todas as chaves (pelo prefixo de 8 caracteres), junto com seus escopos, a data do último uso e a contagem de usos. Você pode revogar uma chave a qualquer momento; a revogação é imediata e irreversível.

Escopos

Os escopos são cumulativos. Você pode conceder qualquer subconjunto ao criar uma chave. Uma requisição a um endpoint cujo escopo necessário você não possui retorna HTTP 403 com error.code = "FORBIDDEN" e error.reason = "insufficient_scope"; a mensagem lista todos os escopos que seriam aceitos.

Escopos padrão

Escopos por recurso

Para o menor privilégio possível, você pode conceder escopos <recurso>:<ação>. Cada um é aceito nos endpoints do próprio recurso além do escopo padrão correspondente, e nunca vai além desse recurso.

Exemplos: forms:write permite que uma chave faça POST /v1/kyc/forms/:formId/send, mas não crie requisições de verificação; verifications:read + analytics:read formam uma chave somente leitura para um painel. <recurso>:manage inclui todas as outras ações desse recurso.

Restrições

Além dos escopos, uma chave pode ser restrita ao ser criada ou editada:

• Formulários — a chave só pode usar os formulários que você escolher e só acessar verificações criadas por meio deles. Veja Restrição de formulário.
• Fluxos de trabalho — a chave só pode acionar os fluxos de automação (pelo nome) que você escolher. Veja Restrição de fluxo de trabalho.
• Lista de permissão de IP — endereços IPv4/IPv6 e faixas CIDR (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Uma requisição de qualquer outro endereço — ou cujo endereço não possa ser identificado — é recusada com 403 ip_not_allowed.
• Validade — após o expiresAt, a chave retorna 401 api_key_expired.

Todas as restrições são vazias (sem restrição) por padrão, e as chaves existentes não têm nenhuma. As chaves criadas antes da existência de restrições (kyk_…) e os tokens do conector nunca são restritos.

Restrição de formulário

Uma chave restrita aos formulários X e Y fica confinada a esses formulários e às verificações criadas por meio deles. Uma verificação é "criada por meio de um formulário" quando foi enviada com POST /v1/kyc/forms/:formId/send (por qualquer chave ou pelo painel), enviada pelo link público do formulário, ou criada com POST /v1/kyc/requests e um formId.

Uma renovação, ou uma verificação de beneficiário final (UBO) gerada por uma verificação de empresa, pertence ao mesmo formulário da verificação de origem.

Restrição de fluxo de trabalho

A Certivant não tem nenhum endpoint que indique um fluxo pelo nome, por isso esta restrição não gera um 403 em nenhuma chamada. Ela controla quais fluxos de automação podem ser executados para as verificações que a chave cria:

• Toda verificação criada pela chave (POST /v1/kyc/requests, /requests/batch, POST /v1/kyc/forms/:formId/send, POST /v1/kyc/conferences com um solicitante inline) registra a chave de origem.
• A partir daí, para essa verificação apenas, somente os fluxos cujo nome está na lista da chave podem ser executados — seja qual for o evento que dispare: o solicitante enviando o formulário, uma decisão, um revisor, um webhook ou a própria chave. Execuções disparadas por evento de qualquer outro fluxo são ignoradas, assim como um fluxo que outro fluxo inicie por meio de uma etapa Trigger workflow.
• A lista atual da chave se aplica enquanto a chave existir; portanto, reduzir ou remover a restrição tem efeito imediato sobre as verificações em andamento. Se a chave for excluída, vale a lista que ela tinha quando criou a verificação.
• Verificações criadas pelo painel, por um solicitante em um formulário público, ou por uma chave sem restrição de fluxo não são afetadas, e o mesmo vale para qualquer outro gatilho (agendamentos, outras verificações).
• Uma renovação e as verificações de beneficiário final (UBO) de uma empresa herdam a restrição da verificação de origem.

O motivo de erro workflow_not_allowed é reservado para endpoints que recebem um fluxo pelo nome; atualmente nenhum existe.

Chaves de produção vs. de teste

As chaves ck_live_… são para produção e as chaves ck_test_… para desenvolvimento e CI. O ambiente é uma etiqueta, não um sandbox: as respostas trazem X-Certivant-Environment, o painel exibe o selo, e os registros de auditoria guardam o prefixo da chave — mas uma chave de teste lê e grava os mesmos dados que uma chave de produção. O único sandbox é o de nível de locatário: até que a Certivant verifique sua organização, os recursos de verificação ao vivo ficam bloqueados para todas as chaves. Use uma organização separada se precisar de dados de teste totalmente separados.

Boas práticas de ambiente

• Uma chave por ambiente. Crie chaves separadas para local, staging e production. Se um ambiente for comprometido, os outros dois continuam seguros.
• Dê nomes descritivos às chaves. payments-service-prod-2026Q2 é melhor que key1. O nome aparece no registro de auditoria.
• Defina uma validade para chaves que você só precisa temporariamente — para migrações, demonstrações ou acesso de terceiros. A Certivant rejeita a chave automaticamente quando o expiresAt passa.
• Rotacione anualmente. Crie uma nova chave, troque seu serviço para ela e revogue a antiga quando a nova já tiver processado tráfego sem erros.
• Nunca faça commit de chaves no git. Use seu gerenciador de segredos — AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical ou, no mínimo, arquivos .env listados no .gitignore.

Rotação sem interrupção

Use Rotacionar na chave (Desenvolvedor → Chaves de API), ou a API:

POST /api/kyc/api-keys/{id}/rotate        (sessão do painel, permissão api.access)
{ "overlapHours": 24 }

sequenceDiagram
  participant You
  participant Dashboard
  participant Service
  participant Certivant
  You->>Dashboard: Rotate key (overlap 24 h)
  Dashboard-->>You: ck_live_new_… (same scopes, restrictions, IP allowlist)
  You->>Service: Deploy with new key in env var
  Service->>Certivant: Authenticated requests with new key
  Note over Certivant: Old key still works until the overlap ends
  Certivant-->>Service: Old key → 401 api_key_rotated after the overlap

1. Rotacione a chave. A substituta copia o nome, os escopos, as restrições, a lista de permissão de IP e a validade; o valor completo é exibido uma única vez.
2. Implante seu serviço com a nova chave durante a sobreposição (de 0 a 168 horas, padrão de 24). A chave antiga continua funcionando até lá, e o campo Último uso no painel mostra se algo ainda a utiliza.
3. Quando a sobreposição terminar, a chave antiga retorna 401 api_key_rotated. Use overlapHours: 0 para revogá-la imediatamente. Você também pode revogá-la antes, manualmente.

O que acontece quando uma chave é revogada

A próxima requisição com a chave revogada retorna 401. Não há período de tolerância. Se você revogar por engano uma chave que ainda precisa, crie uma nova — não é possível desfazer a revogação.

Endpoints públicos (sem chave)

Um pequeno conjunto de endpoints é intencionalmente público — eles não exigem uma chave de API:

• GET /api/health e GET /api/status — sondagens operacionais.
• GET /api/branding — configuração pública de identidade visual para a interface hospedada.
• GET /api/kyc/public/status?ref=… — consulta de status do solicitante pela referência externa.
• GET /api/kyc/public/forms/:slug e os endpoints de envio de formulário — usados pela interface hospedada de formulários.

Eles são documentados para fins de completude, mas a maioria das integrações nunca os chama diretamente — a URL de sessão hospedada cuida de toda a interação pública.

Registro de auditoria

Toda chamada autenticada à API é registrada em KycAuditLog com o prefixo da chave que fez a chamada, o endpoint e o tipo de ator (api). Você pode revisar o histórico em KYC → Registro de auditoria no painel. Os registros de auditoria são mantidos durante todo o período de vida da requisição à qual se referem.