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

# Autenticação

> Autentique requisições com uma API key vinculada à sua organização.

Todas as rotas sob `/v1` exigem uma API key no header `Authorization` usando o
esquema Bearer.

```http theme={null}
Authorization: Bearer bvt_live_...
```

<Warning>
  Nunca envie a API key na URL, em parâmetros de query, no código-fonte ou em
  mensagens de suporte. Trate-a como uma senha.
</Warning>

## Criar uma chave

1. Acesse [Configurações → Avançado → API Keys](https://app.bevits.com/settings/api-keys).
2. Selecione **Criar API key**.
3. Dê um nome que identifique o consumidor, como `Leme` ou `Claude Code`.
4. Mantenha o acesso **somente leitura** para consultar os recursos desta versão.
5. Copie e armazene o segredo imediatamente. Ele não será exibido novamente.

Somente owners e administradores da organização podem gerenciar API keys.

## Usar a chave

Salve a credencial no gerenciador de segredos da sua plataforma ou em uma
variável de ambiente local:

```bash theme={null}
export BEVITS_API_KEY="bvt_live_..."
```

Em seguida, envie o header em todas as chamadas:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.bevits.com/v1/segments \
    --header "Authorization: Bearer $BEVITS_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.bevits.com/v1/segments", {
    headers: {
      Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Bevits API returned ${response.status}`);
  }

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

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.bevits.com/v1/segments",
      headers={"Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}"},
      timeout=30,
  )
  response.raise_for_status()
  page = response.json()
  ```
</CodeGroup>

## Escopos

| Escopo  | Permite                                                                                    |
| ------- | ------------------------------------------------------------------------------------------ |
| `read`  | Consultar identidade, clientes, compras, segmentos, tags, atributos, flows e campanhas.    |
| `write` | Reservado para operações de escrita. Não é necessário para os endpoints de leitura atuais. |

Use sempre o menor privilégio necessário. Para Leme e agentes que apenas
consultam dados, uma chave com `read` é suficiente.

## Revogar uma chave

Revogue imediatamente uma chave que tenha sido exposta ou não seja mais usada.
Na mesma página de API Keys, selecione a credencial e confirme **Revogar**.
Chamadas posteriores passam a receber `401 authentication_error`.

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key.",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}
```