CLI: Authentication

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

Value Purpose
KEITO_API_KEY or api_key Sent as Authorization: Bearer <api-key>
KEITO_ACCOUNT_ID or account_id Sent as Keito-Account-Id

The API key must be a full-access integration key beginning with kto_.... A workspace Administrator creates this separate key under Settings > API & Developers > Integration keys, selects the member or Agent identity that will use the CLI, and chooses All permitted operations. The account ID is the Keito Company ID from Settings > API & Developers > Company ID.

The Personal read-only sync key is not CLI-compatible. It cannot list tracking tasks or create, update, stop, or discard time entries. There is no setting that upgrades a sync key; an Administrator must create a separate full-access integration key.

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 compatible credentials to the local config file. Keito CLI v0.1.8 and later identifies personal read-only sync keys and explains why they cannot be saved for CLI tracking.

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,
  "credential_type": "full_access",
  "cli_compatible": true,
  "can_track_time": true
}

auth status exits with code 1 for missing, invalid, or non-CLI-compatible credentials. A personal read-only sync key produces an authentication error that identifies the credential type rather than a response-parsing error.

Show Current User

keito auth whoami
keito auth whoami --json

This calls the production API and returns the identity resolved from the current credentials. Full-access responses include company. The reduced personal read-only sync response intentionally does not, although auth whoami can still render that limited identity.

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.