Saltar para o conteúdo principal

Autenticação

Enviando a chave​

Toda requisição às rotas /v1 precisa da chave de API no cabeçalho Authorization:

Authorization: Bearer vld_live_7crbnGcZZEHpGN8PQ2j7tSOZKPEVhkpWMoVFbXgxbjm

Se a sua ferramenta não permitir esse cabeçalho, use X-API-Key com a mesma chave:

X-API-Key: vld_live_7crbnGcZZEHpGN8PQ2j7tSOZKPEVhkpWMoVFbXgxbjm
Nunca envie a chave na URL

Requisições com a chave na URL (por exemplo ?api_key=) são recusadas com o erro 401. URLs ficam gravadas em históricos, registros de servidores e proxies.

Formato da chave​

As chaves começam com vld_live_, seguido de 43 letras e números. O prefixo ajuda ferramentas de varredura de segredos (como as do GitHub) a reconhecer uma chave publicada por engano.

O Validades guarda apenas uma impressão digital (hash) da chave. Por isso ela é mostrada uma única vez e não pode ser recuperada.

A chave é da organização​

A chave pertence à organização, e não à pessoa que a criou. Se essa pessoa sair da organização, a chave continua funcionando até ser revogada. O painel mostra quem criou cada chave.

Tudo o que é feito com a chave aparece no registro de atividades da organização como "Via API (chave "Nome")".

Escopos​

EscopoPermite
readtodas as consultas (GET)
writecriar (POST) e alterar (PATCH)
deleteexcluir (DELETE)

Uma chamada sem o escopo necessário recebe 403 com o código insufficient_scope, e o campo details.required_scope informa o escopo que faltou.

Dê a cada integração só o que ela precisa. Uma integração que apenas lê os lotes não deve ter write nem delete.

Validade e revogação​

  • Ao criar a chave, você pode definir uma validade (30, 90, 180 ou 365 dias). Depois disso ela para de funcionar.
  • No painel, Revogar desativa a chave na hora. As integrações que a usam passam a receber 401.
  • Para trocar uma chave sem parar a integração: crie a nova, atualize o seu sistema e só então revogue a antiga. Por isso o limite é de 5 chaves ativas.

Se uma chave vazar​

  1. Revogue a chave imediatamente no painel (validades.com → Time → API).
  2. Crie uma chave nova e atualize a sua integração.
  3. Confira em Logs e uso as chamadas feitas com a chave antiga (data, rota, IP).
  4. Se encontrar algo estranho, fale com o suporte informando os request_id das chamadas.

Lembre que, pelos Termos de Uso da API, tudo o que é feito com uma chave válida da organização é considerado feito pela organização.

Erros de acesso​

SituaçãoHTTPcode
Chave ausente, inválida, revogada ou expirada401invalid_api_key
API não liberada para a organização403api_access_not_enabled
Acesso suspenso403api_access_suspended
Espaço pessoal (não é organização)403workspace_not_eligible
Nova versão dos termos não aceita depois do prazo403terms_not_accepted
Organização sem assinatura ativa402subscription_inactive
Chave sem o escopo necessário403insufficient_scope

Sem assinatura ativa, a API não responde nenhuma requisição, nem as de leitura. Ela volta a funcionar assim que a assinatura for regularizada.