# Set an env name to a cloud secret

PUT

/v1/system/tenants/{tenantId}/env/{name}

```sh
curl --request PUT \
  --url 'https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/env/example?envName=example&scopeKind=tenant' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "cloudSecret": "example", "ifRevision": 1 }'
```

Sets an env name, at a scope of the tenant and one env, to a version of a secret the operator’s cloud holds. A pack service whose pack declares the name is given it by that name, and its host reads the value from the cloud as the pack service’s own account: the runtime keeps the name, never a value. Every pack service runs as that one account, so only a system key sets one. The version is a number, so what a pack service runs changes only when this does. A name set both to this and to a plain value or a secret is `pack-env-ambiguous`. The tenant sees the name as set (`GET /v1/env/cloud-secrets`, the pack-env check), never the path. Recorded as `env-set` in the tenant’s audit record, naming the system key and marked `cloudSecret`, never with the path. Every write bumps `revision`; `ifRevision` guards it. Takes `system:env-refs`. A closing tenant is frozen: `409 tenant-closing`.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.5.0/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**tenantId**

required

string format: uuid

The tenant’s id.

**name**

required

string

\>= 1 characters

Env entry name (opaque string within the workspace + envName).

### Query Parameters

**envName**

required

Per-environment slug. `[a-z][a-z0-9-]{0,62}` — RFC-1035-like label.

string

/^\[a-z]\[a-z0-9-]{0,62}$/

`[a-z][a-z0-9-]{0,62}`. Required on every env + secrets route.

**scopeKind**

required

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Required on every env + secrets route. Tenant carries no `scopeId`; org / project require `scopeId`.

**scopeId**

string

\>= 1 characters

Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (the workspace is implicit from the session). Malformed combinations return 400 scope-invalid.

### Header Parameters

**Idempotency-Key**

string

\>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered `503 idempotency-store-unavailable` with `Retry-After`: nothing ran, so retry with the same key (from 0.3.0).

## Request Bodyrequired

application/json

object

**cloudSecret**

required

A version of a secret in the operator’s cloud, by its resource name: `projects/<project>/secrets/<secret>/versions/<number>`, with a project id (6 to 30 lowercase letters, digits and hyphens) or number, a secret id of 1 to 255 letters, digits, `_` and `-`, and a version number (never `latest` or an alias). A secret whose id starts with `kp-` is never one: those are the pack services’ own copies.

string

**ifRevision**

Set only if the stored one is at this revision (`409 env-write-conflict`).

integer

##### Examplegenerated

```json
{
  "cloudSecret": "example",
  "ifRevision": 1
}
```

## Responses

### 200

The cloud secret now.

application/json

An env name, at a scope and env, given to a pack service as a version of a secret the operator’s cloud holds. The pack service’s cloud reads it, as the pack service’s own account: the runtime keeps the name, never a value.

object

**scope**

required

One of:

- **object**

  object

  **kind**

  required

  string

  Allowed values: tenant

  **tenantId**

  required

  string

- **object**

  object

  **kind**

  required

  string

  Allowed values: org

  **tenantId**

  required

  string

  **orgId**

  required

  string

- **object**

  object

  **kind**

  required

  string

  Allowed values: project

  **tenantId**

  required

  string

  **projectId**

  required

  string

**envName**

required

Per-environment slug. `[a-z][a-z0-9-]{0,62}` — RFC-1035-like label.

string

/^\[a-z]\[a-z0-9-]{0,62}$/

**name**

required

string

**cloudSecret**

required

A version of a secret in the operator’s cloud, by its resource name: `projects/<project>/secrets/<secret>/versions/<number>`, with a project id (6 to 30 lowercase letters, digits and hyphens) or number, a secret id of 1 to 255 letters, digits, `_` and `-`, and a version number (never `latest` or an alias). A secret whose id starts with `kp-` is never one: those are the pack services’ own copies.

string

**revision**

required

integer

**createdAt**

required

string format: date-time

**updatedAt**

required

string format: date-time

##### Example

```json
{
  "scope": {
    "kind": "tenant"
  }
}
```

### 400

`cloudSecret` isn’t a numbered version of a secret, or names a `kp-` secret (`cloud-secret-invalid`); or a missing or malformed scope or `envName`, or another field in the body (`bad-input`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 403

A tenant’s key or session (`system-principal-required`), or a system key without `system:env-refs` (`system-scope-missing`). On a runtime serving one tenant, a system key reaches these only when it runs a pack service per deployment.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No tenant with that id, or a purged one (`tenant-not-found`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 409

`ifRevision` mismatch (`env-write-conflict`); the tenant is closing (`tenant-closing`); or an Idempotency-Key reused with another body. Or `env-not-served`: this runtime keeps every value under the env it serves (whoami’s `servedEnv`, with `refusesOtherEnvs`), so a value under another env would never be read. `details.envName` is the env asked for, `details.servedEnv` the one to use. A secret that a provider, MCP endpoint or webhook endpoint registered before names under that env, at the scope it’s read at, is still written: it’s read there. Nothing is stored otherwise.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 413

The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 500

Server error (unmapped domain code or framework crash).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 501

This runtime keeps no cloud secrets (`cloud-secrets-unsupported`): hosted, for one.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 503

The `Idempotency-Key` store couldn’t be read before the request ran (`idempotency-store-unavailable`), so nothing was changed; `Retry-After` (whole seconds) says when to try again with the same key.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`DELETE /v1/system/tenants/{tenantId}/env/{name}`: Remove an env name's cloud secret](https://docs.kindgi.com/v0.5.0/reference/api/operations/systemenvdeletecloudsecret.md)
- [`GET /v1/system/tenants`: List tenants](https://docs.kindgi.com/v0.5.0/reference/api/operations/systemtenantslist.md)
- [`POST /v1/system/tenants`: Create a tenant](https://docs.kindgi.com/v0.5.0/reference/api/operations/systemtenantscreate.md)
- [`GET /v1/system/tenants/{tenantId}`: Read a tenant](https://docs.kindgi.com/v0.5.0/reference/api/operations/systemtenantsget.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.5.0/reference/errors.md#bad-input)
- [Error code `cloud-secret-invalid`](https://docs.kindgi.com/v0.5.0/reference/errors.md#cloud-secret-invalid)
- [Error code `cloud-secrets-unsupported`](https://docs.kindgi.com/v0.5.0/reference/errors.md#cloud-secrets-unsupported)
- [Error code `env-not-served`](https://docs.kindgi.com/v0.5.0/reference/errors.md#env-not-served)
- [Error code `env-write-conflict`](https://docs.kindgi.com/v0.5.0/reference/errors.md#env-write-conflict)
- [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.5.0/reference/errors.md#idempotency-store-unavailable)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.5.0/reference/errors.md#request-too-large)
- [Error code `system-principal-required`](https://docs.kindgi.com/v0.5.0/reference/errors.md#system-principal-required)
- [Error code `system-scope-missing`](https://docs.kindgi.com/v0.5.0/reference/errors.md#system-scope-missing)
- [Error code `tenant-closing`](https://docs.kindgi.com/v0.5.0/reference/errors.md#tenant-closing)
- [Error code `tenant-not-found`](https://docs.kindgi.com/v0.5.0/reference/errors.md#tenant-not-found)
- [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)