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 |