secrets

Create or update a stored secret reference for the signed-in user.

Create or update a stored secret reference for the signed-in user. Use this for API keys, PATs, webhook HMAC secrets, and other static credentials already available inside trusted execution. Do not persist OAuth access or refresh tokens here — /connect/oauth and createAuthenticatedFetch / integrationTokenRefresh write those on the connection. Optional expires_at is a UTC ISO timestamp or YYYY-MM-DD; null clears expiry. Updates that only change description or expiry may omit value. Use /connect/secret-set for user-provided API key, PAT, and credential entry or rotation. Host use is authorized through secret policy approvals. Saved secrets are consumed in outbound fetch calls by placeholder, e.g. {{secret:name}}, resolved only for approved hosts.

Org permission: secret:write.

put/v1/secrets/{scope}/{name}

Request

  • Base URL: https://api.kody.codes
  • URL: https://api.kody.codes/v1/secrets/{scope}/{name}
  • Auth: HTTP bearer

Path parameters

scope'session' | 'package' | 'user' required

Storage scope that owns the secret.

namestring required

Secret name to create or update.

Request body

valuestring

Secret value to persist. Required when creating a secret. Optional on updates that only change description or expires_at. Write-only and must never be returned to the caller.

descriptionstring

Optional human-readable description of the secret.

expires_atstring nullable

Optional UTC ISO expiry (or YYYY-MM-DD). Null or empty clears expiry. Omit on update to leave the existing expiry unchanged.

kind'secret' | 'url' | 'login' | 'signing'

Optional credential kind (ADR 0068), set together with a value. "secret" (default) is a Key used by {{secret:name}} placeholders. "url", "login", and "signing" are opt-in kinds a package reads through a scoped credential client, never as raw text; they need hosts.

hostsstring[]

Hosts an opt-in kind may be sent to: exact hosts or one wildcard level such as *.example.com. Set together with a value. Keys keep using host approvals instead.

providerstring nullable

Optional provider slug (for example "github") a scoped credential client matches package needs against. Null clears it. Keys used by placeholders ignore it.

Response

Success.

namestring required
scope'session' | 'package' | 'user' required
descriptionstring required
package_idstring nullable required
allowed_hostsstring[] required
allowed_packagesstring[] required
created_atstring required
updated_atstring required
expires_atstring nullable required
ttl_msinteger nullable required
kind'secret' | 'url' | 'login' | 'signing'

Credential kind, returned when this call set opt-in fields.

providerstring nullable

Changes

No recorded changes to this operation across all 2 revisions of this API.