# Authentication

Set up API tokens for Kopai

Learn how to authenticate your applications with Kopai.

## API Tokens

Kopai uses bearer tokens for API authentication. All OTLP requests must include your token in the Authorization header.

## Creating a Token

1. Navigate to **Settings** → **Access Tokens**
2. Click **Generate New Token**
3. Give your token a descriptive name
4. Copy the token immediately (it won't be shown again)

## Using Your Token

Include your token in the `Authorization` header:

```bash
Authorization: Bearer YOUR_TOKEN
```

Or set via environment variable:

```bash
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_TOKEN"
```

## Token Best Practices

- Use separate tokens for different environments (dev, staging, prod)
- Rotate tokens regularly
- Never commit tokens to source control
- Revoke unused tokens promptly

## CLI Authentication

To query traces, logs, and metrics from the terminal, create a read-only CLI token.

### Create a CLI Token

1. Navigate to **Settings** → **Access Tokens**
2. Click **Generate New Token**
3. Select **CLI** as the token type
4. Give your token a descriptive name
5. Copy the token immediately (it won't be shown again)

:::note
CLI tokens are read-only — they can query traces, logs, and metrics but cannot write telemetry data. They expire after 90 days by default.
:::

### Login

**npm:**

```bash
npx @kopai/cli login
```

**pnpm:**

```bash
pnpm dlx @kopai/cli login
```

**yarn:**

```bash
yarn dlx @kopai/cli login
```

Paste your CLI token at the prompt. The token is saved to `.kopairc` in the current directory.

| Flag | Description |
|------|-------------|
| `--url <url>` | Set the Kopai server URL (default: `https://kopai.app`) |
| `--global` | Save to `~/.kopairc` instead of `./.kopairc` |
| `--config <path>` | Use a custom config file path |

If `.kopairc` is not in your `.gitignore`, the CLI will warn you.

### Logout

**npm:**

```bash
npx @kopai/cli logout
```

**pnpm:**

```bash
pnpm dlx @kopai/cli logout
```

**yarn:**

```bash
yarn dlx @kopai/cli logout
```

Removes the token from `.kopairc`. Other config fields (like `url`) are preserved.

| Flag | Description |
|------|-------------|
| `--global` | Remove token from `~/.kopairc` |
| `--config <path>` | Use a custom config file path |

### Verify Authentication

**npm:**

```bash
npx @kopai/cli whoami
```

**pnpm:**

```bash
pnpm dlx @kopai/cli whoami
```

**yarn:**

```bash
yarn dlx @kopai/cli whoami
```

Displays your token prefix and server URL. Validates the token against the server if reachable.

### Config File

The CLI stores credentials in `.kopairc`:

```json
{
  "token": "kpi_...",
  "url": "https://api.kopai.app/v2"
}
```

Resolution order: `--config` flag → `./.kopairc` → `~/.kopairc`

### Token Expiry

CLI tokens expire after 90 days. When your token expires:

1. Create a new CLI token in the dashboard (**Settings** → **Access Tokens**)
2. Run `npx @kopai/cli login` and paste the new token