Secret values and credential references
Secret metadata, secret values and the integrations that reference them have different visibility and recovery requirements.
Store and reference a credential
| Field | Constraint or behavior |
|---|---|
name | Unique within the project; 1–63 characters, starting with a lowercase letter or digit and then allowing lowercase letters, digits, dots, underscores and hyphens. |
value | Nonempty; at most 64 KiB in encoded bytes. Responses do not echo it. |
description, labels | Optional metadata for finding and managing the credential. |
version | Returned as a JSON string; retain it when tracking credential changes. |
authSecretRef | A connection uses the stored secret by name. The name does not grant permission to send that credential to any destination. |
Inspect and list
Use POST /api/v1/secrets/get-metadata with name, or POST /api/v1/secrets/list with zero-based page and pageSize. The current default page size is 50, with a maximum of 100. Continue through the result's pages to enumerate the project; a single page is not the complete inventory. These operations return metadata without values.
Remove a credential
Call POST /api/v1/secrets/delete with name. If a registered custom MCP server refers to it, the current API refuses ordinary deletion and reports the known references. Change those references first, or deliberately use force: true with management authority and accept the affected integrations failing on later resolution.
Already-sent requests, external copies and provider revocation remain separate. A failed deletion can leave an incomplete result; do not infer that the old credential is intact. Deleting an already absent secret succeeds with a false deleted result, which may be omitted from the JSON response.