Skip to main content
Pré-requisito: Antes de autenticar, você precisa ter uma chave de API válida. Se ainda não possui, consulte a página Chaves de API para aprender como criar e gerenciar suas chaves.

​
Como funciona

Todas as APIs da Plataforma ID utilizam autenticação baseada em chaves de API (API Keys). Para autenticar suas requisições, você deve incluir sua chave no header HTTP x-api-key de cada requisição.

​
Fluxo de Autenticação

1

Obtenha sua chave de API

Gere uma chave de API através da plataforma seguindo as instruções em Chaves de API.
2

Inclua o header nas requisições

Adicione o header x-api-key com o valor da sua chave em todas as requisições para as APIs.
3

Realize a requisição

Execute a requisição normalmente. A API validará automaticamente sua chave.

​
Formato da Requisição

​
Header HTTP

Todas as requisições autenticadas devem incluir o seguinte header: 
x-api-key: SUA_CHAVE_DE_API

​
Exemplo Prático

Substitua SUA_CHAVE_DE_API pela chave gerada na plataforma (ex: 12345678-abcd-90ef-ghij-1234567890kl): 
curl -X POST https://api.valid.TODO.com/... \
  -H "x-api-key: 12345678-abcd-90ef-ghij-1234567890kl" \
  -H "Content-Type: application/json" \
  -d '{ // Seu payload aqui }'

​
Códigos de Resposta

​
Autenticação Bem-Sucedida

Quando a chave de API é válida, você receberá a resposta normal do endpoint solicitado (geralmente código 200 ou 201).

​
Erros de Autenticação

​
401
Unauthorized
Chave de API ausente ou inválidaPossíveis causas:
  • Header x-api-key não foi incluído na requisição
  • Chave de API está incorreta ou mal formatada
  • Chave de API foi revogada
Solução: Verifique se você está enviando o header correto com uma chave válida e ativa.
​
403
Forbidden
Chave de API válida mas sem permissõesPossíveis causas:
  • Chave não tem permissão para acessar o recurso solicitado
  • Projeto não tem o produto necessário ativado
Solução: Verifique as permissões da chave e se o produto está ativo no projeto.

​
Exemplo de Erro

// 401
{
  "fault": {
    "faultstring": "Invalid ApiKey",
    "detail": {
      "errorcode": "oauth.v2.InvalidApiKey"
    }
  }
}

​
Boas Práticas de Segurança

  • Use variáveis de ambiente para armazenar suas chaves, nunca as inclua diretamente no código
  • Não commite chaves em repositórios Git ou sistemas de controle de versão
  • Use gerenciadores de secrets como AWS Secrets Manager, HashiCorp Vault, ou similares em produção
Exemplo com variáveis de ambiente
# .env
PIID_API_KEY=12345678-abcd-90ef-ghij-1234567890kl
Uso em código
// JavaScript/Node.js
const apiKey = process.env.PIID_API_KEY;

const response = await fetch(url, {
  headers: {
    'x-api-key': apiKey
  }
});
  • Crie chaves separadas para cada ambiente (desenvolvimento, homologação, produção)
  • Use nomes descritivos que identifiquem claramente o ambiente e a aplicação
  • Rotacione chaves periodicamente, especialmente em produção
Exemplo de nomenclatura:
  • prod-api-webapp-2025
  • staging-api-backoffice
  • dev-api-mobile-app
  • Sempre use HTTPS para fazer requisições às APIs
  • Nunca envie chaves via query parameters ou URLs
  • Use apenas headers HTTP para transmitir as chaves
Se suspeitar que uma chave foi exposta:
  1. Revogue imediatamente a chave comprometida na plataforma
  2. Gere uma nova chave para substituir a anterior
  3. Atualize sua aplicação com a nova chave
  4. Investigue como a chave foi comprometida para evitar recorrência
  • Acompanhe o uso de cada chave através da plataforma
  • Configure alertas para uso anormal ou excessivo
  • Revogue chaves não utilizadas regularmente
  • Audite acessos periodicamente para garantir segurança

​
Próximos Passos

Agora que você sabe como autenticar suas requisições, explore as APIs disponíveis:

Background Check API

Verificação de empresas e pessoas físicas (KYB/KYC)

Liveness API

Detecção de vivacidade e autenticação biométrica

Gerenciar Chaves

Criar, renomear e revogar chaves de API

Guia Rápido

Tutorial completo de integração

​
Perguntas Frequentes

Tecnicamente sim, mas não é recomendado. O ideal é criar uma chave específica para cada aplicação ou serviço. Isso facilita:
  • Rastreamento de uso por aplicação
  • Revogação granular em caso de problemas
  • Gerenciamento de permissões específicas
Quando você revoga uma chave:
  • A chave para de funcionar imediatamente
  • Todas as requisições usando essa chave retornarão erro 401
  • A ação é irreversível - você precisará criar uma nova chave
  • Suas aplicações precisarão ser atualizadas com a nova chave
Não, as chaves de API não expiram automaticamente. Elas permanecem válidas até que você as revogue manualmente. Porém, é uma boa prática de segurança rotacionar suas chaves periodicamente (a cada 90-180 dias).
Atualmente, as APIs da Plataforma ID utilizam exclusivamente autenticação via header x-api-key. Outros métodos de autenticação (Bearer token, OAuth, etc.) não são suportados no momento.
As permissões das chaves são gerenciadas automaticamente com base nos produtos ativados no projeto. Uma chave terá acesso apenas às APIs dos produtos que estão vinculados ao projeto onde a chave foi criada.