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 CLI needs a full-access kto_... key. Eligible active internal Members and Managers can create their own under Settings > API & Developers > Personal API keys: enter a name, choose All permitted operations in API key access, then select Create API key. The key follows your current permissions and record access. Copy the secret immediately and the Company ID from the same page.

A workspace Administrator can also issue a key under Integration keys, selecting the member or Agent identity that will use the CLI and All permitted operations. Agent identities need this administrator-issued key.

The Personal read-only sync key is not CLI-compatible. It cannot list tracking tasks or create, update, stop, or discard time entries. Existing read-only keys stay read-only, including when rotated. Create a separate key with All permitted operations, then update the CLI credentials; do not rotate a sync key expecting write access. See API key creation.

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.