Set an env name to a cloud secret
const url = 'https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/env/example?envName=example&scopeKind=tenant';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"cloudSecret":"example","ifRevision":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The tenant’s id.
Env entry name (opaque string within the workspace + envName).
Query Parameters
Section titled “Query Parameters”Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.
[a-z][a-z0-9-]{0,62}. Required on every env + secrets route.
Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.
Required on every env + secrets route. Tenant carries no scopeId; org / project require scopeId.
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
Section titled “Header Parameters”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
Section titled “Request Bodyrequired”object
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.
Set only if the stored one is at this revision (409 env-write-conflict).
Examplegenerated
{ "cloudSecret": "example", "ifRevision": 1}Responses
Section titled “Responses”The cloud secret now.
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
Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.
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.
Example
{ "scope": { "kind": "tenant" }}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).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}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.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No tenant with that id, or a purged one (tenant-not-found).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}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.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}This runtime keeps no cloud secrets (cloud-secrets-unsupported): hosted, for one.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}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.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
DELETE /v1/system/tenants/{tenantId}/env/{name}: Remove an env name's cloud secretGET /v1/system/tenants: List tenantsPOST /v1/system/tenants: Create a tenantGET /v1/system/tenants/{tenantId}: Read a tenant- Error code
bad-input - Error code
cloud-secret-invalid - Error code
cloud-secrets-unsupported - Error code
env-not-served - Error code
env-write-conflict - Error code
idempotency-store-unavailable - Error code
request-too-large - Error code
system-principal-required - Error code
system-scope-missing - Error code
tenant-closing - Error code
tenant-not-found - Every error code