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
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
| Escopo | Permite |
|---|---|
read | todas as consultas (GET) |
write | criar (POST) e alterar (PATCH) |
delete | excluir (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
- Revogue a chave imediatamente no painel (validades.com → Time → API).
- Crie uma chave nova e atualize a sua integração.
- Confira em Logs e uso as chamadas feitas com a chave antiga (data, rota, IP).
- Se encontrar algo estranho, fale com o suporte informando os
request_iddas 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ção | HTTP | code |
|---|---|---|
| Chave ausente, inválida, revogada ou expirada | 401 | invalid_api_key |
| API não liberada para a organização | 403 | api_access_not_enabled |
| Acesso suspenso | 403 | api_access_suspended |
| Espaço pessoal (não é organização) | 403 | workspace_not_eligible |
| Nova versão dos termos não aceita depois do prazo | 403 | terms_not_accepted |
| Organização sem assinatura ativa | 402 | subscription_inactive |
| Chave sem o escopo necessário | 403 | insufficient_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.