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 eight-endpoint allowlist; no /tasks, no CLI tracking, and no writes
Full-access key (All permitted operations) 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 eight permitted requests, response contracts, and assignment-scoped project visibility.

Read-only sync keys cannot gain write access, including through rotation. For the CLI or writes, create a new key with All permitted operations. Eligible Members and Managers can create it for themselves; Administrators can issue keys for other members or Agents.

Creating an API Key

  1. Log in to the Keito web app.
  2. Navigate to Settings -> API & Developers.
  3. Under Personal API keys, enter a descriptive key name.
  4. In API key access, select All permitted operations for the CLI or writes, or Read-only sync for the limited sync contract above. Choose the access explicitly; there is no default selection.
  5. Select Create API key and copy the kto_... secret immediately. It will not be shown again.
  6. Copy the Company ID shown on the same page.

Eligible active internal Members and Managers can use these self-service steps. The key acts as you and checks your current role, granular permissions, and record access on every request. All permitted operations adds no permissions beyond those you have in Keito. Role, permission, and assignment changes apply without rotation. Workspace credential policy, recent authentication, and multi-factor requirements still apply.

Administrators see Integration keys and can use the steps below to select the identity a key acts as. Agent identities cannot use the personal self-service path.

Replace an Existing Read-Only Key

Create a separate key with All permitted operations, replace the secret in your integration or run keito auth login again, and verify the operations you need. Revoke the old key when it is no longer used. Rotating a read-only sync key only replaces its secret; the new key remains read-only.

Full-Access Key for a Member or Agent

A workspace Administrator can also create a CLI-compatible or write-capable key bound to a selected identity:

  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 eight read operations are sufficient.
  • Use separate credentials for each user, agent, CI job, or integration.
  • For custom integrations, keep keys in server-side systems; never embed them in browser or mobile application code.
  • If you use a user-bound full-access key with the first-party Keito for Chrome extension, enter it only in that extension’s connection form. The extension exchanges it with Keito for a browser session; do not put it in a website, script, or another extension.
  • 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.

Building an integration for multiple customers? Read the partner integrations guide and apply through the Integration Partner track so we can confirm the supported authorisation path for your app.

Planning access

Every planning operation requires Business. Existing personal sync keys can read /api/v2/planning/me when an administrator grants the separate own-schedule permission. Plan-screen visibility does not grant that permission. See Planning API for access, pagination and safe writes.