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

# Get your API key

> Create a BotGauge project API key, set BOTGAUGE_API_KEY, load it from a .env file, and avoid the 401 errors caused by using the wrong token.

BotGauge accepts traces signed with an API key from the BotGauge cloud console. Keys belong to a project, so traces sent with a key land in that project.

## Create a key

**1. Sign in**

Go to [cloud.botgauge.com](https://cloud.botgauge.com) and sign in.

**2. Complete onboarding for your workspace**

Follow the onboarding prompts for your workspace.

**3. Generate a key**

Open the project you want to trace into, go to **Settings, Project, API keys**, and choose **Create key**. Give it a name that says what uses it, such as `CI - GitHub Actions`, then copy the key. It starts with `bg_`.

> [!WARNING]
>
> BotGauge shows the full key once. Only the last four characters are kept for display afterwards, so store the key in your secrets manager before you close the dialog.

Creating, listing, and revoking keys requires the workspace **Admin** role. See [Roles and permissions](https://www.botgauge.com/docs/platform/roles-and-permissions.md) if you can't see the API keys page.

## Put the key where BotGauge looks for it

The SDK and `botgauge instrument` both read the key from the `BOTGAUGE_API_KEY` environment variable. Set it in the shell or deployment that runs your app.

```bash terminal theme={null}
export BOTGAUGE_API_KEY="bg_..."
```

### Using a .env file

BotGauge doesn't read `.env` files itself. Load the file before `tracing.init()`, for example with `python-dotenv` (`pip install python-dotenv`).

```text .env theme={null}
BOTGAUGE_API_KEY=bg_...
```

```python app.py theme={null}
from dotenv import load_dotenv

from botgauge import tracing

load_dotenv()  # copies BOTGAUGE_API_KEY from .env into the environment
tracing.init()
```

For [zero-code runs](https://www.botgauge.com/docs/tracing/zero-code.md), hand the file to the launcher instead, because your app's own `load_dotenv()` runs too late for it.

```bash terminal theme={null}
botgauge instrument --env-file .env python app.py
```

> [!TIP]
>
> Keep `.env` out of version control. Add it to `.gitignore` before the first commit.

## Use the right token

Use the key you generated in the console. BotGauge rejects other tokens with `401`, including the session token your browser receives when you sign in to the console.

If a key is rejected, the SDK logs a single line on the first `401` or `403`, `botgauge: BotGauge rejected the API key (401 ...)`, and keeps your app running. Export happens on a background thread, so a bad key never crashes your application. See [Troubleshooting](https://www.botgauge.com/docs/tracing/troubleshooting.md) for the full list of messages.

Generate a project keyOpen [BotGauge](https://cloud.botgauge.com) to create and copy an API key for your project.

[Create an API key →](https://cloud.botgauge.com)

## Rotate and revoke

Revoking a key stops it working immediately and can't be undone. To rotate, create the new key first, deploy it, confirm traces still arrive, then revoke the old one. The API keys table shows each key's last four characters and when it was last used, which helps you confirm nothing still depends on a key before you revoke it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.