Autenticação e Autorização

A API da Lazy Data usa autenticação por Bearer token para identificar a conta, validar permissões e aplicar regras de plano, saldo, escopos e restrição de IP. Para acessar endpoints protegidos, envie sua chave de API no header Authorization.

Authorization: Bearer <sua_chave_de_api>

Não envie sua chave de API em query string, corpo da requisição, logs públicos ou aplicações frontend sem backend intermediário.

Antes de começar

Você precisa criar uma credencial no painel da Lazy Data.

Obter credenciais

Veja como criar, gerenciar e configurar permissões de uma chave de API.

Ao criar a credencial, confira:

escopos habilitados;
ambiente de uso;
restrição de IP, quando aplicável;
permissões da conta ou subconta;
limites e regras comerciais do plano.

Header de autenticação

Todas as rotas protegidas da API principal usam o header:

Authorization: Bearer <sua_chave_de_api>

Exemplo de requisição:

curl --request GET \
  --url "https://api.lazydata.com.br/v1/search/datasets/pf" \
  --header "Authorization: Bearer <sua_chave_de_api>"

O token deve ser enviado exatamente no formato Bearer, com espaço entre Bearer e a chave.

Exemplo com JavaScript

const response = await fetch("https://api.lazydata.com.br/v1/search/datasets/pf", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <sua_chave_de_api>"
  }
});

const data = await response.json();
console.log(data);

Exemplo com Python

import requests

response = requests.get(
    "https://api.lazydata.com.br/v1/search/datasets/pf",
    headers={
        "Authorization": "Bearer <sua_chave_de_api>"
    },
)

print(response.json())

Autenticação vs autorização

Autenticação confirma que a chave enviada é válida. Autorização confirma se essa chave pode executar o recurso solicitado.

Conceito	O que valida	Exemplo de erro
Autenticação	Se a chave existe, está ativa e foi enviada corretamente.	`401`
Autorização	Se a chave possui escopo, plano, saldo, IP e permissão para o recurso.	`403`

Trate 401 e 403 separadamente. 401 normalmente exige corrigir ou trocar a credencial. 403 exige revisar permissão, plano, saldo, IP, subconta ou política do recurso.

Escopos

As credenciais podem ter escopos para limitar quais recursos podem ser acessados. Exemplos de escopos:

Escopo	Uso
`search`	Consultas por CPF, CNPJ, processo, veículo e datasets.
`validation`	Validação cadastral e comparação facial.
`enrichment`	Criação, configuração, execução e acompanhamento de enriquecimentos.
`storage`	Listagem, upload, download, renomeação e exclusão de arquivos.
`monitoring`	Configuração, criação, listagem, detalhe e cancelamento de monitoramentos.

Os nomes e disponibilidade dos escopos podem variar conforme a configuração da conta. Use apenas os escopos necessários para cada integração.

Restrição de IP

Credenciais podem ter restrição de IP para aceitar requisições apenas de origens autorizadas. Use essa proteção quando a integração roda em servidores com IP fixo ou previsível. Boas práticas:

habilite restrição de IP em integrações backend;
evite usar chaves restritas em ambientes com IP dinâmico sem controle;
mantenha listas de IP atualizadas;
crie credenciais separadas para produção, homologação e testes.

Subcontas

Quando uma credencial pertence a uma subconta, a API também valida as permissões e limites configurados para essa subconta. Uma requisição pode ser bloqueada quando:

a subconta não possui acesso ao recurso;
a subconta atingiu o limite mensal;
a conta principal removeu a permissão;
o plano da conta principal não permite o recurso.

Sandbox

Alguns endpoints aceitam chamadas de teste sem consumo de saldo. Para usar sandbox, envie o header:

x-ambient: sandbox

O header de sandbox não substitui autenticação. Em rotas protegidas, envie também:

Authorization: Bearer <sua_chave_de_api>

Ambiente de teste

Veja quais fluxos aceitam sandbox e como validar integrações com segurança.

Uploads assinados

O serviço de upload usa autenticação própria por assinatura temporária. Uploads para upload.lazydata.com.br não usam Authorization: Bearer no envio do arquivo. Em vez disso, envie:

X-LazyData-Upload-Signature: <assinatura_de_upload>

A assinatura de upload é gerada por uma chamada autenticada na API principal. Depois disso, o envio do arquivo usa apenas a assinatura temporária.

Upload para enriquecimento

Veja como enviar bases para upload.lazydata.com.br/enrichment.

Upload para armazenamento

Veja como enviar arquivos para upload.lazydata.com.br/storage.

Erros comuns

Status	Motivo comum	Como tratar
`401`	Header `Authorization` ausente.	Envie `Authorization: Bearer <chave>`.
`401`	Credencial inválida, revogada ou malformada.	Gere ou revise a chave usada.
`403`	Escopo ausente.	Habilite o escopo necessário na credencial.
`403`	IP não autorizado.	Atualize a restrição de IP ou use origem permitida.
`403`	Plano, saldo ou limite bloqueando a operação.	Revise plano, saldo, fatura, limite mensal ou subconta.

Exemplo de erro:

{
  "code": 401,
  "message": "Credencial da API inválida.",
  "result": null
}

Segurança

Use uma credencial por aplicação, ambiente ou integração crítica.
Mantenha chaves em variáveis de ambiente ou cofre de segredos.
Rotacione credenciais periodicamente.
Revogue chaves antigas ou comprometidas.
Não compartilhe chaves em tickets, prints, planilhas ou logs.
Não exponha credenciais em aplicações frontend.
Habilite restrição de IP quando possível.
Conceda apenas os escopos necessários para cada integração.

Próximos passos

Obter credenciais

Crie e configure sua chave de API.

Ambiente de teste

Teste integrações sem consumir saldo.

Introdução da API

Veja padrão de resposta, erros e boas práticas gerais.

Códigos de erro

Consulte erros de autenticação, permissão, plano, saldo e provedor.

Primeiros passos

Utilidades

Funcionalidades

Webhook

Autenticação e Autorização

Antes de começar

Obter credenciais

Header de autenticação

Exemplo com JavaScript

Exemplo com Python

Autenticação vs autorização

Escopos

Restrição de IP

Subcontas

Sandbox

Ambiente de teste

Uploads assinados

Upload para enriquecimento

Upload para armazenamento

Erros comuns

Segurança

Próximos passos

Obter credenciais

Ambiente de teste

Introdução da API

Códigos de erro

​Antes de começar

Obter credenciais

​Header de autenticação

​Exemplo com JavaScript

​Exemplo com Python

​Autenticação vs autorização

​Escopos

​Restrição de IP

​Subcontas

​Sandbox

Ambiente de teste

​Uploads assinados

Upload para enriquecimento

Upload para armazenamento

​Erros comuns

​Segurança

​Próximos passos

Obter credenciais

Ambiente de teste

Introdução da API

Códigos de erro

Antes de começar

Header de autenticação

Exemplo com JavaScript

Exemplo com Python

Autenticação vs autorização

Escopos

Restrição de IP

Subcontas

Sandbox

Uploads assinados

Erros comuns

Segurança

Próximos passos