Skip to content
Kapten
Esc
↑↓navigate↵open⌘Jpreview
On this page

Authentication

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, from environment variables. Logins are saved as contexts, one per organization, so you can switch between them.

Log in

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:

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:

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 with only the Roles the job needs, then set its client ID and its secret:

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:

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

Was this page helpful?