---
title: Authentication
description: Log in to Kapten from the CLI, switch between organizations with saved contexts, and authenticate CI jobs as an OAuth application.
---

The CLI runs commands either as you, after `kapten login`, or as an [OAuth application](/api#authentication), from environment variables. Logins are saved as **contexts**, one per organization, so you can switch between them.

## Log in

```bash
kapten login
```

The CLI shows a code such as `WDJB-MJHT` and a page to open. It opens the page in your browser when it can. Otherwise, or with `--no-browser`, open it yourself, on this machine or any other: logging in works over SSH. On the page, check that the code matches, approve it and pick an organization. The code expires after ten minutes.

The login is saved as a context named after the organization. `--name` gives it another name:

```bash
kapten login --name work
```

`kapten whoami` shows who commands run as, and in which organization. It says to log in again when the session has ended. `kapten logout` removes the active context's credentials, `kapten logout <context>` another one's, and `kapten logout --all` every context's.

## Switch between organizations

Each login is a context, and one context is active. Commands run in the active context, unless `--context` names another one:

```bash
kapten auth list                       # the contexts, the active one marked with *
kapten auth use work                   # make work the active context
kapten --context personal projects list
```

## Where credentials are saved

The CLI saves each context's tokens in the operating system's keychain: Keychain on macOS, the Secret Service on Linux, the Credential Manager on Windows. When no keychain is available, it saves them in `credentials.json`, a file only your user can read, in the Kapten config directory (`~/.config/kapten` on Linux), and warns you. `kapten auth list` shows where each context's credentials are.

On a machine with no keychain, such as a container, set `KAPTEN_CREDENTIALS_STORE=file` to use the file directly.

Access tokens are renewed while you use the CLI. Your login lasts as long as the browser session that approved it: when you sign out of the console, log in again.

## Run in CI

In a CI job, the CLI authenticates as an OAuth application of your organization, with no login. [Create an OAuth application](/api#authentication) with only the Roles the job needs, then set its client ID and its secret:

```bash
export KAPTEN_CLIENT_ID=cli_…
export KAPTEN_CLIENT_SECRET=kapten_sk_…
kapten projects list
```

For an application you registered a public key for, set the private key instead of the secret, as a PEM or JWK, in `KAPTEN_CLIENT_PRIVATE_KEY` or in a file named by `KAPTEN_CLIENT_PRIVATE_KEY_FILE`:

```bash
export KAPTEN_CLIENT_ID=cli_…
export KAPTEN_CLIENT_PRIVATE_KEY_FILE=deploy-key.pem
```

The CLI requests a token for each run and keeps it in memory: nothing is saved. Store the secret or the key in your CI's secret store.

When both are possible, `--context` wins over the environment variables, and the environment variables win over the active context. `kapten login` refuses to run while `KAPTEN_CLIENT_ID` is set.

## Environment variables

| Variable | Use |
| --- | --- |
| `KAPTEN_CLIENT_ID` | Authenticate as this OAuth application, with no login |
| `KAPTEN_CLIENT_SECRET` | The OAuth application's client secret |
| `KAPTEN_CLIENT_PRIVATE_KEY` | The OAuth application's private key, as a PEM or JWK, instead of a secret |
| `KAPTEN_CLIENT_PRIVATE_KEY_FILE` | A file holding that private key |
| `KAPTEN_CREDENTIALS_STORE` | `file` saves logins in the config directory instead of the keychain |
| `KAPTEN_CONFIG_DIR` | The directory of the CLI's contexts and file credentials |
