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

# Authentication

> Authenticate requests with an API key linked to your organization.

Every route under `/v1` requires an API key in the `Authorization` header using
the Bearer scheme.

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

<Warning>
  Never send an API key in a URL, query parameter, source code, or support
  message. Treat it like a password.
</Warning>

## Create a key

1. Go to [Settings → Advanced → API Keys](https://app.bevits.com/settings/api-keys).
2. Select **Create API key**.
3. Choose a name that identifies the consumer, such as `Leme` or `Claude Code`.
4. Keep the key **read-only** to query the resources available in this version.
5. Copy and store the secret immediately. It will not be displayed again.

Only organization owners and administrators can manage API keys.

## Use the key

Store the credential in your platform's secret manager or in a local
environment variable:

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

Then send the header with every request:

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

## Scopes

| Scope   | Allows                                                                                  |
| ------- | --------------------------------------------------------------------------------------- |
| `read`  | Query identity, customers, purchases, segments, tags, attributes, flows, and campaigns. |
| `write` | Reserved for write operations. It is not required by the current read endpoints.        |

Always use the least privilege required. A `read` key is enough for Leme and
agents that only query data.

## Revoke a key

Immediately revoke a key that has been exposed or is no longer used. On the API
Keys page, select the credential and confirm **Revoke**. Subsequent requests
receive `401 authentication_error`.

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