Manage Secrets

Kupe manages sync definitions rather than secret values: the API tells the platform which vault path to read and which cluster/namespace pairs to sync it into, and the vault itself holds the data.

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.

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 overwriting 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.

Permissions

Listing and reading secret definitions works with the readonly role. Creating, updating, and deleting a secret definition all need the admin role; a 403 Forbidden is returned for readonly keys or members.