> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação API

> Aprenda como autenticar suas requisições nas APIs da Plataforma ID usando chaves de API.

<Info>
  **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](/plataforma/chaves-de-api) para aprender como criar e gerenciar suas chaves.
</Info>

## 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

<Steps>
  <Step title="Obtenha sua chave de API">
    Gere uma chave de API através da plataforma seguindo as instruções em [Chaves de API](/plataforma/chaves-de-api).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Realize a requisição">
    Execute a requisição normalmente. A API validará automaticamente sua chave.
  </Step>
</Steps>

## 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`):

<CodeGroup>
  ```bash cURL theme={"theme":"catppuccin-latte"}
  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 }'
  ```

  ```javascript JavaScript theme={"theme":"catppuccin-latte"}
  const response = await fetch('https://api.valid.TODO.com/...', {
    method: 'POST',
    headers: {
      'x-api-key': '12345678-abcd-90ef-ghij-1234567890kl',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      // Seu payload aqui
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={"theme":"catppuccin-latte"}
  import requests

  url = "https://api.valid.TODO.com/..."
  headers = {
      "x-api-key": "12345678-abcd-90ef-ghij-1234567890kl",
      "Content-Type": "application/json"
  }
  payload = {
      # Seu payload aqui
  }

  response = requests.post(url, json=payload, headers=headers)
  data = response.json()
  ```

  ```java Java theme={"theme":"catppuccin-latte"}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();

  String requestBody = """
  {
      // Seu payload aqui
  }
  """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.valid.TODO.com/..."))
      .header("x-api-key", "12345678-abcd-90ef-ghij-1234567890kl")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(requestBody))
      .build();

  HttpResponse<String> response = client.send(request,
      HttpResponse.BodyHandlers.ofString());
  ```

  ```php PHP theme={"theme":"catppuccin-latte"}
  <?php

  $url = "https://api.valid.TODO.com/...";

  $data = [
      // Seu payload aqui
  ];

  $options = [
      'http' => [
          'header' => [
              "x-api-key: 12345678-abcd-90ef-ghij-1234567890kl",
              "Content-Type: application/json"
          ],
          'method' => 'POST',
          'content' => json_encode($data)
      ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  $result = json_decode($response, true);
  ?>
  ```
</CodeGroup>

## 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

<ResponseField name="401" type="Unauthorized">
  **Chave de API ausente ou inválida**

  Possí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.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  **Chave de API válida mas sem permissões**

  Possí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.
</ResponseField>

### Exemplo de Erro

```json theme={"theme":"catppuccin-latte"}
// 401
{
  "fault": {
    "faultstring": "Invalid ApiKey",
    "detail": {
      "errorcode": "oauth.v2.InvalidApiKey"
    }
  }
}
```

## Boas Práticas de Segurança

<AccordionGroup>
  <Accordion title="Armazene chaves com segurança" icon="lock">
    * **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

    ```bash Exemplo com variáveis de ambiente theme={"theme":"catppuccin-latte"}
    # .env
    PIID_API_KEY=12345678-abcd-90ef-ghij-1234567890kl
    ```

    ```javascript Uso em código theme={"theme":"catppuccin-latte"}
    // JavaScript/Node.js
    const apiKey = process.env.PIID_API_KEY;

    const response = await fetch(url, {
      headers: {
        'x-api-key': apiKey
      }
    });
    ```
  </Accordion>

  <Accordion title="Gerencie chaves por ambiente" icon="layer-group">
    * **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`
  </Accordion>

  <Accordion title="Proteja suas chaves em trânsito" icon="shield">
    * **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
  </Accordion>

  <Accordion title="Revogue chaves comprometidas" icon="triangle-exclamation">
    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
  </Accordion>

  <Accordion title="Monitore o uso das chaves" icon="chart-line">
    * **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
  </Accordion>
</AccordionGroup>

## Próximos Passos

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

<CardGroup cols={2}>
  <Card title="Background Check API" icon="magnifying-glass" href="/plataforma/background-check/apresentacao">
    Verificação de empresas e pessoas físicas (KYB/KYC)
  </Card>

  <Card title="Liveness API" icon="brain" href="/plataforma/liveness/hub/apresentacao">
    Detecção de vivacidade e autenticação biométrica
  </Card>

  <Card title="Gerenciar Chaves" icon="key" href="/plataforma/chaves-de-api">
    Criar, renomear e revogar chaves de API
  </Card>

  <Card title="Guia Rápido" icon="rocket" href="/plataforma/guia-rapido">
    Tutorial completo de integração
  </Card>
</CardGroup>

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="Posso usar a mesma chave em múltiplas aplicações?">
    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
  </Accordion>

  <Accordion title="O que acontece se eu renovar/revogar uma chave?">
    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
  </Accordion>

  <Accordion title="As chaves de API expiram?">
    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).
  </Accordion>

  <Accordion title="Posso usar autenticação Bearer token?">
    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.
  </Accordion>

  <Accordion title="Como limito o acesso de uma chave a APIs específicas?">
    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.
  </Accordion>
</AccordionGroup>