Manage Secrets

The API manages the secret definition and its sync targets. Secret values themselves live in the tenant vault, while Kupe uses the managed secret resource to decide which clusters and namespaces should receive them.

For the full schema, see Reference: secrets.

Create a secret with sync targets

POST /api/v1/tenants/{tenant}/secrets

export KUPE_TENANT="<tenant>"

curl -X POST \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/secrets" \
  -d '{
    "name": "db-password",
    "secretPath": "production/db-password",
    "sync": [
      { "cluster": "production", "namespace": "default" },
      { "cluster": "production", "namespace": "backend", "secretName": "database-credentials" }
    ]
  }'

Field	Required	Description
name	Yes	Identifier for the managed secret resource (DNS-safe).
secretPath	Yes	Path in the tenant’s vault where the actual secret data lives.
sync	No	Array of sync targets. Each target needs cluster and namespace; secretName is optional and overrides the Kubernetes Secret name.

The actual secret values are not part of this request. Today, the Kupe API manages the sync definition rather than the vault data itself.

Add a sync target to an existing secret

PATCH replaces the full sync list. To add a new target, fetch the current list, append, and PATCH:

curl -X PATCH \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/secrets/db-password" \
  -d '{
    "sync": [
      { "cluster": "production", "namespace": "default" },
      { "cluster": "production", "namespace": "backend", "secretName": "database-credentials" },
      { "cluster": "staging", "namespace": "default" }
    ]
  }'

To remove all sync targets (stops syncing without deleting the secret), pass an empty array:

{ "sync": [] }

Use the If-Match header with the ETag from a prior GET to avoid clobbering concurrent edits — see Scale and upgrade clusters for the optimistic locking pattern.

Check sync status

A GET on the secret returns status.syncStatuses, an array showing the current state of each target cluster/namespace. See Reference: get secret.

Delete a managed secret

curl -X DELETE \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/secrets/db-password"

This removes the Kupe resource and stops future syncing. The values in the vault are not deleted by this API call, and existing synced Kubernetes secrets are not removed automatically.