---
title: "Assert authorization for, and optionally atomically persist, multiple secret references for the signed-in user (API k..."
method: POST
path: "/v1/secrets/batch"
tags: ["secrets"]
---

# Assert authorization for, and optionally atomically persist, multiple secret references for the signed-in user (API k...

`POST /v1/secrets/batch`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/secrets/batch`
- Auth: HTTP bearer

Assert authorization for, and optionally atomically persist, multiple secret references for the signed-in user (API keys, PATs, HMAC secrets). Use assertOnly before a multi-write that must not partially succeed. Do not use this for OAuth access or refresh tokens — `/connect/oauth` and `createAuthenticatedFetch` / `integrationTokenRefresh` persist those on the connection. 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`.

## Request body

- object
  - `secrets` object[], required: Secrets to assert and optionally persist. Order is preserved. Do not include OAuth access or refresh tokens — those persist on the connection.
    - `name` string, required: Secret name to create or update.
    - `value` string: Secret value to persist. Required unless assertOnly is true. Write-only and must never be returned to the caller.
    - `description` string: Optional human-readable description of the secret.
    - `expires_at` string, nullable: Optional UTC ISO expiry (or YYYY-MM-DD). Null or empty clears expiry. Omit on update to leave the existing expiry unchanged.
    - `scope` 'session' | 'package' | 'user', required: Storage scope that owns the secret.
  - `assertOnly` boolean: When true, only authorize the writes (no values required) and do not persist. Use before a multi-write that must not partially succeed.

## Response `200`

Success.

- object
  - `ok` true, required
  - `assertOnly` boolean, required
  - `secrets` object[], required
    - `name` string, required
    - `scope` 'session' | 'package' | 'user', required
    - `description` string, required
    - `package_id` string, nullable, required
    - `allowed_hosts` string[], required
    - `allowed_packages` string[], required
    - `created_at` string, required
    - `updated_at` string, required
    - `expires_at` string, nullable, required
    - `ttl_ms` integer, nullable, required
    - `kind` 'secret' | 'url' | 'login' | 'signing': Credential kind, returned when this call set opt-in fields.
    - `provider` string, nullable
    - `inject` union
      - object
        - `kind` 'header', required
        - `name` string, required
        - `format` string, required
      - object
        - `kind` 'basic', required
        - `valueAs` 'username' | 'password', required
        - `other` string
      - object
        - `kind` 'query', required
        - `param` string, required
    - `placement` object, nullable: Where placeholders may be filled. Null means anywhere. Returned when this call set opt-in fields.
      - `headers` union
        - true
        - string[]
      - `query` true
      - `path` true
      - `body` true

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)