Authentication

Keito API v2 supports multiple API key types. API key requests need both:

  • Authorization: Bearer <kto_...>
  • Keito-Account-Id: <company_id>

The Keito-Account-Id value is your Keito Company ID. It scopes the request to the correct company and is required for API key authentication.

Choose a Key Type

Use the least-privileged key that supports the integration:

Key type Intended use
Personal read-only sync key Export one user’s time and read the users, clients, and assigned projects available through its fixed seven-endpoint allowlist; no /tasks, no CLI tracking, and no writes
Full-access integration key Keito CLI and API operations currently permitted to its bound human or Agent identity; never implicit Administrator access

Read Personal Read-Only Sync Keys before configuring a directory or time-entry sync. It documents the seven permitted requests, response contracts, and assignment-scoped project visibility.

The personal read-only sync key cannot be upgraded. If you need the Keito CLI, /api/v2/tasks, or any create, update, stop, restart, or delete operation, a workspace Administrator must create a separate full-access integration key bound to the identity performing that work.

Creating an API Key

  1. Log in to the Keito web app.
  2. Navigate to Settings -> API & Developers.
  3. Create the appropriate key type for the integration. Full-access integration keys are Administrator-created; eligible users can create their own personal read-only sync key.
  4. Copy the kto_... API key immediately. It will not be shown again.
  5. Copy the Company ID shown on the same page.

Full-Access Key for a Member or Agent

A workspace Administrator creates a CLI-compatible or write-capable key as follows:

  1. Under Integration keys, enter a descriptive key name.
  2. Select the active internal member or Agent identity that will use the key.
  3. Select All permitted operations.
  4. Select Create integration key and copy the secret immediately.
  5. Deliver the key and Company ID to that identity through a secure secret-sharing channel.

The key inherits the selected identity’s current permissions and project assignments. Do not create a key under My account and share it with another user: it would act with the Administrator’s identity and permissions instead of the intended user’s.

Using Your API Key

Base URL:

https://app.keito.ai/api/v2

Example request:

curl https://app.keito.ai/api/v2/users/me \
  -H "Authorization: Bearer kto_xxxxx" \
  -H "Keito-Account-Id: your_company_id"

SDK Configuration

In the SDKs:

// Node SDK
const keito = new Keito({
  apiKey: process.env.KEITO_API_KEY,
  accountId: process.env.KEITO_ACCOUNT_ID,
});
# Python SDK
client = Keito(
    api_key=os.environ["KEITO_API_KEY"],
    account_id=os.environ["KEITO_ACCOUNT_ID"],
)

Environment Variables

Variable Description
KEITO_API_KEY Your kto_... API key
KEITO_ACCOUNT_ID Your Keito Company ID, sent as Keito-Account-Id
KEITO_WORKSPACE_ID Legacy CLI alias for KEITO_ACCOUNT_ID

Find the Company ID in Keito under Settings -> API & Developers -> Company ID.

Security Best Practices

  • Treat API keys like passwords.
  • Never commit API keys to source control.
  • Use environment variables or a secrets manager.
  • Prefer a personal read-only sync key when its seven read operations are sufficient.
  • Use separate credentials for each user, agent, CI job, or integration.
  • Keep keys in server-side systems; never embed them in browser or mobile application code.
  • Revoke keys immediately if they are exposed.

OAuth Tokens

Some partner integrations use WorkOS Connect JWTs instead of kto_... API keys. JWT requests use the Authorization header only; the company is resolved from token claims.