> ## Documentation index
> The full klickops handbook index is at https://klickops.io/llms.txt
> The HTML of this page is at https://klickops.io/en/docs/tokens
> Language: en

# API tokens

Long-lived credentials for scripts, CI and assistants, scoped to a role and optionally to single projects.

## What it is

An API token authenticates something that is not a person: a CI pipeline, a deployment script, an AI assistant. It belongs to the organization rather than to you, and it carries a role of its own.

That ownership is the point. A token tied to your account stops working the day you leave, taking the pipeline with it. An organization token survives you and can be revoked without touching anybody's login.

## When you'd use it

- Deploying from your own CI.
- A cron job that runs `klops` somewhere.
- Giving an [AI assistant](/docs/mcp) access without handing over your session.

## Create one

1. Go to **Tokens** in the organization.
2. Name it after what will use it, not after yourself. `github-actions-shop` tells the next person what breaks if they revoke it; `jan-token` does not.
3. Pick the role. Viewer for anything that only reads.
4. Optionally scope it to specific projects. A token without a project scope reaches the whole organization.
5. Copy the value. It is shown once and never again.

## Using it

```bash
export KLICKOPS_SERVER=https://klickops.example.com
export KLICKOPS_TOKEN=klp_…
klops apps list --project shop -o json
```

Against the API directly it is an ordinary bearer token:

```bash
curl -H "Authorization: Bearer klp_…" \
  https://klickops.example.com/api/klickops/projects/shop/apps
```

## Settings reference

| Setting | Default | What it does |
| --- | --- | --- |
| Name | none | What this token is for. Shown in the list and in the audit log. |
| Role | viewer | What it may do: `viewer`, `editor` or `admin`. |
| Projects | all | Restricts it to named projects. Empty means the whole organization. |
| Last used | never | When it last authenticated, so you can tell a live token from a forgotten one. |

## Limits and gotchas

- **The value is shown once.** Lost means rotate, not recover.
- **A token does not expire on its own.** It works until revoked, which is why the last-used column matters: it is how you find the ones nobody needs any more.
- **Scope by role first, projects second.** Most CI pipelines only need `editor` on one project, and most assistants only need `viewer`.
- **Revoking is immediate and unrecoverable.** Anything using it fails on the next call, with exit code `3` from the CLI.

> [!Careful]
> A token in a repository is a token in everybody's hands. Put it in your CI's secret store, and if one is ever committed, revoke it rather than rewriting history: assume it was read.

## Related

- [klops CLI](/docs/cli) reads `KLICKOPS_TOKEN` directly.
- [MCP server](/docs/mcp) should get a scoped token rather than your session.
- [Members and roles](/docs/members) for the same question about people.