---
title: "List available secret references for the signed-in user."
method: GET
path: "/v1/secrets"
tags: ["secrets"]
---

# List available secret references for the signed-in user.

`GET /v1/secrets`

## Request

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

List available secret references for the signed-in user. Results include metadata such as names, credential ids (for accessGrant), descriptions, allowed hosts, allowed packages, and package_id for package-scoped secrets — never plaintext values. Explicit listing includes caller-owned package-scoped metadata from execute (no package runtime); using a package secret still requires package context. From a package runtime, self-authored and adopted packages see user secrets they can already read; unadopted community forks see only explicitly granted user secrets. Listing a secret does not approve a host: outbound `fetch` still resolves `{{secret:name}}` (optionally `{{secret:name|scope=user}}`) only for approved hosts. Use `kody.secretList({ scope })` inside execute-time code for the same metadata. Use `/connect/secret-set` for user-provided API key, token, and credential entry or rotation.

Org permission: `secret:use`.

## Query parameters

- `scope` 'session' | 'package' | 'user': Optional scope filter. When omitted, list all accessible scopes. Package-scoped metadata is included for caller-owned secrets (with package_id) even without a package runtime; session secrets stay session-bound. Using a package secret still requires package context.

## Response `200`

Success.

- object
  - `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
    - `credential_id` string, required: Stable credential id. accessGrant uses it as resource_id.

## 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)