tokens

Mint a scoped API token for this account.

Mint a scoped API token for this account. The token value is returned once. 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. A token-authenticated caller can only grant scopes it holds and cannot outlive its own max_expires_at.

Org permission: none (touches no org data).

post/v1/tokens

Request

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

Request body

namestring required

Label shown in token lists, e.g. kody-cli on laptop.

scopesstring[] required

Org-permission scopes to grant. There is no write-implies-read hierarchy. A token can only mint tokens with scopes it holds. 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.

org_binding'org' | 'user'

org (default): bind to the current request org. user: person-owned token; each call picks an org with ?org=<slug> (default personal). Existing org-bound tokens stay unchanged.

profilestring

Optional connection profile name. The token’s package access is limited to that profile’s grants. Experimenters only.

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

max_lifetime_secondsinteger

Absolute lifetime cap 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.