CLI: Authentication

The Keito CLI authenticates with the production API v2 using two values:

ValuePurpose
KEITO_API_KEY or api_keySent as Authorization: Bearer <api-key>
KEITO_ACCOUNT_ID or account_idSent as Keito-Account-Id

The API key is a long-lived kto_... key. The account ID is the Keito Company ID from Settings > API & Developers > Company ID.

Interactive Login

keito auth login

auth login prompts for the API key and account/company ID, validates them with GET /api/v2/users/me, and writes the validated credentials to the local config file.

The config file is the only persisted credential store. The current CLI does not use the macOS Keychain, Linux Secret Service, or Windows Credential Manager.

Non-Interactive Auth

Use environment variables for agents, scripts, and CI jobs:

export KEITO_API_KEY="kto_xxxxx"
export KEITO_ACCOUNT_ID="your_company_id"

Environment variables take precedence over the config file, which makes them suitable for CI secrets and temporary overrides.

Credential Resolution

API key resolution order:

  1. KEITO_API_KEY
  2. api_key in config.toml

Account ID resolution order:

  1. --workspace
  2. KEITO_ACCOUNT_ID
  3. KEITO_WORKSPACE_ID legacy alias
  4. account_id in config.toml
  5. workspace_id in config.toml legacy alias

Check Status

keito auth status
keito auth status --json

Example JSON:

{
  "authenticated": true,
  "api_key_source": "config file",
  "account_id": "company_id_here",
  "workspace_id": "company_id_here",
  "api_key_valid": true
}

Show Current User

keito auth whoami
keito auth whoami --json

This calls the production API and returns the user and company resolved from the current credentials.

Logout

keito auth logout

Logout removes api_key, account_id, and workspace_id from the config file. It does not unset environment variables in your shell or CI job.

Security Notes

  • Do not commit config.toml.
  • Store KEITO_API_KEY in a secret manager for CI.
  • Use keito auth status --json as a preflight check before an automated workflow starts a timer.
  • Use a dedicated agent or service user when you want agent work to be attributed separately in Keito.