Sync secrets against a deployment

POST

/v1/deployments/{deploymentId}/secrets

curl --request POST \
  --url https://example.com/v1/deployments/example/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "envName": "example", "secrets": [ { "name": "example", "ref": "example" } ] }'

• Same-origin — path relative to the deployment root.

Deployment-scoped bulk secret sync. Body carries { envName, secrets: Array<{ name, ref } | { name, value }> }. { name, ref } entries validate against SecretBinding.get — no bytes cross the wire; missing → 404 secret-not-found. { name, value } entries write via SecretBinding.set with writeMode: add-version + tags.deployment = deploymentId and return the created reference. The write scope is derived from the deployment record itself (tenant scope, or project scope when the deployment carries a projectId) and CANNOT be overridden on the wire. Requires the secrets:write capability. Idempotency-Key applies.

Authorizations

• bearerAuth

Parameters

Path Parameters

deploymentId

required

string

>= 1 characters

Deployment id assigned by the ledger at register time.

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Body^required

Media typeapplication/json

object

envName

required

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

string

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

secrets

required

Zero or more secret entries. Each entry MUST set exactly one of ref (validate-only) or value (write new version).

Array

One of:

object

object

name

required

string

>= 1 characters

ref

required

Opaque reference to an existing secret record — validated via SecretBinding.get; no bytes cross the wire.

string

>= 1 characters

object

object

name

required

string

>= 1 characters

value

required

Plaintext secret value written via SecretBinding.set with writeMode: add-version. The response returns only the framework-generated reference.

string

Example^generated

{
  "envName": "example",
  "secrets": [
    {
      "name": "example",
      "ref": "example"
    }
  ]
}

Responses

200

Sync complete.

Media typeapplication/json

object

resolved

required

integer

added

required

integer

references

required

Array<object>

object

name

required

string

>= 1 characters

ref

required

Opaque reference — either echoed from the request ({ name, ref } entries) or freshly minted (secret:<envName>/<name>#<version> for { name, value } entries).

string

>= 1 characters

version

required

integer

>= 1

Example^generated

{
  "resolved": 1,
  "added": 1,
  "references": [
    {
      "name": "example",
      "ref": "example",
      "version": 1
    }
  ]
}

400

Malformed request body.

Media typeapplication/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

Example^generated

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

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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

Example^generated

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

403

Bearer token missing secrets:write capability.

Media typeapplication/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

Example^generated

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

404

No deployment with that id, or referenced secret does not exist.

Media typeapplication/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

Example^generated

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

409

Idempotency-Key was reused with a different body, or resource-state conflict.

Media typeapplication/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

Example^generated

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

500

Server error (unmapped domain code or framework crash).

Media typeapplication/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

Example^generated

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