Authentication

The Copera CLI signs you in once and then runs every command as you. This page covers the token types, the login flows, profiles, and how the CLI decides which credential to use when several are available.

Token types

Copera issues two kinds of tokens:

• Personal Access Token (cp_pat_...) — tied to your user account. It covers the full CLI surface and is required for docs, drive, notifications, search, and workspace commands. When in doubt, use a PAT.
• Integration API Key (cp_key_...) — tied to an integration rather than a user. It works for boards and channels only.

tip

Docs and drive operations always require a Personal Access Token with the appropriate workspace permissions. If you see an auth error on copera docs ... or copera drive ..., double-check that you are using a cp_pat_... token.

Surface	cp_pat_ (Personal Access Token)	cp_key_ (Integration API Key)
Boards / tables / rows	Yes	Yes
Channels	Yes	Yes
Docs	Yes	No
Drive	Yes	No
Workspace / search / notifications	Yes	No

Login flows

The fastest way to authenticate is the guided browser flow:

copera auth login

The CLI prints a Copera URL, opens it in your default browser when possible, and asks you to paste the generated token back into the terminal. The printed URL is always available, so the same flow works over SSH, in WSL, or in any terminal where the browser may not open automatically.

If you already have a token, you can save it directly:

Command	When to use it
copera auth login	You want the guided browser flow.
copera auth login --token=<value>	You already have a token and want to save it directly, without opening a browser.
copera auth login --token	You already have a token and want a masked paste prompt — no browser, and the token never lands in your shell history.

Once logged in, your token is stored in ~/.copera.toml and reused for every subsequent command.

Use a token without logging in

For CI, scripts, and AI agents, prefer an environment variable — it overrides every config file and never persists to disk:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

On Windows PowerShell:

$env:COPERA_CLI_AUTH_TOKEN = "cp_pat_xxx"

You can also pass a token per-command with --token, which beats every config file but is lower priority than the environment variable:

copera boards list --token cp_pat_xxx

Inspect the current session

copera auth status     # active profile + where the token came from
copera auth whoami     # who the token belongs to

copera auth status is especially useful when something behaves unexpectedly — it reports whether the CLI picked up a token from your environment, a project config file, or your home directory:

{
  "profile": "default",
  "token_source": "environment variable COPERA_CLI_AUTH_TOKEN",
  "token": "cp_***...***xY2z",
  "configured": true
}

Sign out

copera auth logout

This removes the stored credential. Run copera auth login again at any time.

Token resolution order

When you run a command, the CLI looks for a token in this order — the first one it finds wins:

Priority	Source	Example
1	Environment variable	COPERA_CLI_AUTH_TOKEN=cp_pat_xxx
2	--token flag on the command	copera boards list --token cp_pat_xxx
3	.copera.local.toml in the current directory	Project-local, git-ignored token
4	.copera.toml in the current directory	Shared project defaults
5	~/.copera.toml	User-level fallback

This is intentional:

• CI and agents can override everything else by setting COPERA_CLI_AUTH_TOKEN.
• Per-project tokens live in .copera.local.toml, which should be added to .gitignore.
• Shared project defaults (like a default board_id and table_id, with no token) live in .copera.toml, which is safe to commit.
• Your personal token sits in ~/.copera.toml for everything else.

See Configuration for the full config-file format and how profiles fit in.

Profiles

A profile groups a token together with default resource IDs so you can stop repeating flags like --board and --table. Profiles live in your config files under [profiles.<name>]:

[profiles.default]
token    = "cp_pat_abc123..."
board_id = "66abc123def456789012abcd"

[profiles.work]
token    = "cp_key_xyz789..."
board_id = "66ghi789jkl012345678mnop"
table_id = "66pqr012stu345678901vwxy"

Select a profile per-command or per-shell. If you omit --profile, the CLI uses default (or the default_profile set in your config):

copera boards list --profile work
COPERA_PROFILE=work copera boards list

Sandbox

To target the Copera development environment instead of production, set COPERA_SANDBOX=1. This switches the API base URL to https://api-dev.copera.ai/public/v1 and points copera auth login at the dev web app:

COPERA_SANDBOX=1 copera auth login
COPERA_SANDBOX=1 copera boards list

Where do I get a token?

Generate a token from the Copera web app:

1. Open the workspace you want to access.
2. Go to Settings → Personal Access Tokens (for cp_pat_...) or Settings → Integrations (for cp_key_...).
3. Create a token, copy it, and paste it into the CLI prompt or set it as COPERA_CLI_AUTH_TOKEN.

For more on what each token type can do, see the API Authentication guide.