tokens

Exchange a one-shot `kody_bc_…` bootstrap code for a scoped `kody_at_…` API token.

Exchange a one-shot kody_bc_… bootstrap code for a scoped kody_at_… API token. For @kodycodes/cli auth bootstrap only — not the MCP api tool. No Authorization header; the code is the credential. The code burns on first successful redeem. Lifetime is required on redeem (CLI flags). 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/redeem

Request

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

Request body

codestring required

One-shot kody_bc_… bootstrap code from cliCredentialBootstrap.

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 redeemed token expires. Required with max_lifetime_seconds when lifetime is omitted.

max_lifetime_secondsinteger

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

Response

Success.

idstring required
namestring required
org_idstring required

For org-bound tokens: the fixed org id. For user-owned tokens: the personal org id (placeholder; each request picks an org via ?org=).

org_binding'org' | 'user' required

org: fixed to org_id. user: person-owned; pass ?org=<slug> on each request (default personal org). Membership/grants are checked live.

scopesstring[] required
status'active' | 'expired' | 'revoked' required
idle_ttl_secondsinteger required
expires_atstring required

Sliding expiry. Each successful request pushes it forward.

max_expires_atstring required

Absolute expiry. The token never outlives it.

created_viastring required
created_atstring required
last_used_atstring nullable required
rotated_atstring nullable required
revoked_atstring nullable required
profile_namestring nullable required

Named connection profile this token is bound to, or null for unlimited.

tokenstring required

The bearer token. Shown once; Kody stores only a hash. Send it as Authorization: Bearer <token>.

token_type'Bearer' required

Changes

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