# Sync secrets against a deployment

POST

/v1/deployments/{deploymentId}/secrets

```sh
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" } ] }'
```

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. A secret the tools of this deployment name that was set nowhere when a deploy or a promotion published them is read at that scope, when whoever published them administers it: a deploy needs `admin` there, while a promotion into the Default project needs it only on that project. Requires the `secrets:write` capability. Idempotency-Key applies.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.9/reference/api.md#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, scoped to the caller: the same key from someone else in the tenant 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).

## Request Bodyrequired

application/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

##### Examplegenerated

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

## Responses

### 200

Sync complete.

application/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

##### Examplegenerated

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

### 400

A body that fails validation (`bad-input`), or a secret the store refuses for its name or its value: `reserved-name-prefix`, `secret-name-invalid` (a new name that isn’t 1 to 255 ASCII letters, digits, `.`, `-` and `_` starting with a letter, digit or `_`, with any `.` between two non-`.` characters, or, under `kindgi dev`, isn’t capital letters, digits and underscores, starts with a digit, or is `KINDGI_*`; the message says the rule), `secret-value-too-large`, or `secret-value-invalid` (under `kindgi dev`, a value no env-file quoting can hold so that it reads back unchanged; the message says why).

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

Bearer token missing `secrets:write` capability, or no `admin` on the scope it writes: the deployment’s project, else the tenant.

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 deployment with that id, or one in a project the caller doesn’t read, or referenced secret does not exist.

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

Idempotency-Key was reused with a different body, or resource-state conflict. 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"
  }
}
```

### 429

`secret-provider-rate-limited`: the secrets store’s external provider is limiting the runtime’s requests.

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"
  }
}
```

### 502

`secret-provider-unauthorized`: the secrets store’s external provider refused the runtime’s credentials.

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

`secret-provider-unavailable`: the secrets store’s external provider can’t be reached.

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

- [`GET /v1/deployments/{deploymentId}`: Fetch a signed deployment record](https://docs.kindgi.com/v0.1.9/reference/api/operations/deploymentsget.md)
- [`GET /v1/deployments/{deploymentId}/pack-env`: Show where each name a deployment's pack declares is set](https://docs.kindgi.com/v0.1.9/reference/api/operations/deploymentspackenv.md)
- [`GET /v1/deployments/{deploymentId}/values`: List the values a deployment needs in a project](https://docs.kindgi.com/v0.1.9/reference/api/operations/deploymentsvalueslist.md)
- [`POST /v1/deployments/{deploymentId}/promotions`: Promote a deployment to the next environment](https://docs.kindgi.com/v0.1.9/reference/api/operations/deploymentspromote.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.1.9/reference/errors.md#bad-input)
- [Error code `env-not-served`](https://docs.kindgi.com/v0.1.9/reference/errors.md#env-not-served)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.1.9/reference/errors.md#request-too-large)
- [Error code `reserved-name-prefix`](https://docs.kindgi.com/v0.1.9/reference/errors.md#reserved-name-prefix)
- [Error code `secret-name-invalid`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-name-invalid)
- [Error code `secret-provider-rate-limited`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-provider-rate-limited)
- [Error code `secret-provider-unauthorized`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-provider-unauthorized)
- [Error code `secret-provider-unavailable`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-provider-unavailable)
- [Error code `secret-value-invalid`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-value-invalid)
- [Error code `secret-value-too-large`](https://docs.kindgi.com/v0.1.9/reference/errors.md#secret-value-too-large)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)