Authentication

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:

Authorization: Bearer YOUR_TOKEN

Or set via environment variable:

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

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

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

npx @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:

{
  "url": "https://kopai.app",
  "token": "kpi_..."
}

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