Create secret API Reference

POST

/tenants/{tenant}/secrets

curl --request POST \
  --url https://api.kupe.cloud/api/v1/tenants/acme/secrets \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "database-creds", "secretPath": "services/database/credentials", "sync": [ { "cluster": "production", "keys": [ "username", "password" ], "namespace": "app", "secretName": "db-credentials" } ] }'

Create a new secret. The secretPath points to a key in the tenant’s Vault (a KV v2 store). Optionally configure sync targets to automatically replicate the secret into Kubernetes namespaces across your managed clusters.

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Request Body

Secret configuration

Media type application/json

object

name

Secret name (DNS-safe, 2-63 characters)

string

Example

database-creds

secretPath

Path in the tenant’s Vault (a KV v2 store). Paths under encryption/ are reserved for the platform.

string

Example

services/database/credentials

sync

Optional sync targets to replicate the secret into clusters

Array<object>

object

cluster

Target cluster name

string

Example

production

keys

Selected keys; omitted means the whole entry.

Array<string>

>= 1 items <= 64 items unique items

Example

[
  "username",
  "password"
]

namespace

Target namespace within the cluster

string

Example

app

secretName

Override the Kubernetes secret name (defaults to the secret name)

string

Example

db-credentials

Responses

201

Secret created

Media type application/json

object

createdAt

string

generation

The definition’s generation increments on a change; compare with status.observedGeneration.

integer

name

string

resourceVersion

string

secretPath

string

status

object

conditions

Array<object>

object

key

additional properties

observedRefresh

string

phase

string

Allowed values: Pending Active Degraded Deleting

refresh

object

observedAt

string

pending

pending is true while a requested token differs from observedAt.

boolean

requestedAt

string

syncStatuses

Array<object>

object

cluster

string

deliveredRefresh

string

lastDeliveredAt

string

message

string

namespace

string

phase

Synced confirms delivery into the cluster namespace. Withdrawing tracks a removed target until its source is withdrawn.

string

Allowed values: Pending Synced Failed Withdrawing

reason

string

secretName

string

sync

Array<object>

object

cluster

string

keys

Omitted keys means the whole entry. Selected keys must be unique, with at most 1,024 across all targets.

Array<string>

>= 1 items <= 64 items unique items

namespace

string

secretName

string

Example

{
  "createdAt": "2026-03-10T09:15:00Z",
  "generation": 3,
  "name": "database-creds",
  "resourceVersion": "582019",
  "secretPath": "services/database/credentials",
  "status": {
    "observedRefresh": "2026-10-27T12:00:00Z",
    "phase": "Pending",
    "refresh": {
      "observedAt": "2026-10-27T12:00:00Z",
      "pending": false,
      "requestedAt": "2026-10-27T12:00:00Z"
    },
    "syncStatuses": [
      {
        "cluster": "production",
        "deliveredRefresh": "2026-10-27T12:00:00Z",
        "lastDeliveredAt": "2026-10-27T12:00:01Z",
        "namespace": "app",
        "phase": "Pending",
        "reason": "Delivered",
        "secretName": "db-credentials"
      }
    ]
  },
  "sync": [
    {
      "cluster": "production",
      "keys": [
        "username",
        "password"
      ],
      "namespace": "app",
      "secretName": "db-credentials"
    }
  ]
}

Headers

ETag

string

Resource version

400

Validation error

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Admin access required

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Secret name already exists

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}