tokens

Seed CLI `--local` auth from the current Kody session without a second interactive OAuth: returns a one-shot `kody_bc...

Seed CLI --local auth from the current Kody session without a second interactive OAuth: returns a one-shot kody_bc_… bootstrap code plus a CLI command that includes required lifetime flags. The CLI redeems the code over HTTPS for a scoped kody_at_… (never returned here). Prefer this over tokenCreate for interactive agents already on MCP. Do not paste API tokens into chat. Interactive desktop humans who already ran kody login can skip this. CI/headless may still mint kody_at_ directly. Tokens require an explicit lifetime: lifetime "short" (3600s idle / 86400s max) or "long" (1209600s idle / 7776000s max), or both idle_ttl_seconds (60-1209600) and max_lifetime_seconds (up to 7776000). Each successful request slides expires_at forward, never past max_expires_at. At most 500 active tokens per account; a new mint reclaims the active token(s) with the least remaining life (sooner of idle deadline and absolute expiry), never the caller's own token.

Org permission: none (touches no org data).

post/v1/tokens/bootstrap

Request

  • Base URL: https://api.kody.codes
  • URL: https://api.kody.codes/v1/tokens/bootstrap
  • Auth: HTTP bearer

Request body

namestring

Label for the eventual API token (default kody-cli-bootstrap).

scopesstring[]

Org-permission scopes for the eventual kody_at_ (default: pre-P4 local-execute parity — org:execute + org:read + package/integration/secret/email/job/app/memory use scopes — plus package:write and token:delete). There is no write-implies-read hierarchy. package:read: Read saved packages and package-backed resources. package:execute: Execute saved packages. package:write: Change saved packages and package-backed resources. package:delete: Delete saved packages. package:publish: Publish packages to the community catalog. package:manage_access: Manage package access grants. app:read: Read package apps. app:execute: Run package apps. app:write: Granted app:write in this org. app:delete: Granted app:delete in this org. app:manage_access: Granted app:manage_access in this org. job:read: Read package jobs and workflow runs. job:execute: Run package jobs. job:write: Granted job:write in this org. job:delete: Granted job:delete in this org. job:manage_access: Granted job:manage_access in this org. secret:use: Use secrets without reading plaintext. secret:read: Granted secret:read in this org. secret:write: Change existing secrets (plaintext is never returned). secret:delete: Granted secret:delete in this org. secret:manage_access: Granted secret:manage_access in this org. integration:use: Use connected integrations. integration:read: Read OAuth integrations and connected MCP servers. integration:write: Granted integration:write in this org. integration:delete: Granted integration:delete in this org. integration:manage_access: Granted integration:manage_access in this org. memory:read: Read memories and MCP server instructions. memory:write: Change existing memories. memory:delete: Granted memory:delete in this org. memory:manage_access: Granted memory:manage_access in this org. email:read: Read inboxes and messages. email:send: Send email. email:write: Granted email:write in this org. email:delete: Granted email:delete in this org. email:manage_access: Granted email:manage_access in this org. package:create: Create saved packages. app:create: Granted app:create in this org. job:create: Granted job:create in this org. secret:create: Create new secrets. integration:create: Granted integration:create in this org. memory:create: Create new memories. email:create: Granted email:create in this org. org:read: Read this org’s profile, members, and billing summary. org:write: Change this org’s profile and settings. org:delete: Delete this org. org:execute: Run execute and local CapabilityProxy hops for this org (API tokens need this scope; CLI kody login OAuth is a separate credential). search:read: Run unified Kody search. member:read: Read org members. member:write: Invite and change org members. member:delete: Remove org members. team:read: Read teams. team:write: Create and change teams. team:delete: Delete teams. billing:read: Read billing and plan. billing:write: Change billing and plan. audit:read: Read the org audit log. token:read: List and inspect API tokens. token:delete: Revoke API tokens.

lifetime'short' | 'long'

Required unless idle_ttl_seconds and max_lifetime_seconds are both set. short = 1h idle / 24h max. long = 14d idle / 3mo max. Single-task agents should use short.

idle_ttl_secondsinteger

Seconds without use before the eventual token expires. Required with max_lifetime_seconds when lifetime is omitted.

max_lifetime_secondsinteger

Absolute lifetime cap for the eventual token in seconds. Required with idle_ttl_seconds when lifetime is omitted.

redeem_ttl_secondsinteger

How long the one-shot bootstrap code stays redeemable (default 600).

Response

Success.

bootstrap_codestring required

One-shot code for the CLI (kody_bc_…). Not an API token. Pass it to npx @kodycodes/cli auth bootstrap --code … --lifetime short — do not paste a kody_at_ into chat.

expires_atstring required

Absolute redeem deadline (ISO-8601).

cli_commandstring required

Ready-to-run CLI command that redeems the code into a local KODY_API_TOKEN store entry without a second interactive OAuth. Includes the required lifetime flags.

namestring required
scopesstring[] required
idle_ttl_secondsinteger required
max_lifetime_secondsinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.