secrets.environments.promote

Copy a secret into another environment (or its source reference, if synced)

POST /secrets/api/secrets/{id}/promoteIAM secrets:PromoteSecretChanges stateDestructive

A stored secret: its active value becomes a new version of the same-named secret in the target (created under the same key if missing). A synced secret: give `reference`; without it the answer is 409 with `suggestedReference` (the vault swapped for the target environment). Grants are not copied.

Depending on the resource, the call checks secrets:CreateSecret, secrets:RotateSecret, secrets:UseSecretSource instead; hold all of them to be sure it is allowed.

Request syntax

POST /secrets/api/secrets/{id}/promote
{
  "toEnvironmentId": "string",
  "reference": "string"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • toEnvironmentIdRequired

    string

    The environment to promote into (an environment id), or null for Default, the value every environment falls back to. The secret’s own environment is refused with 400; an unknown id with 404.

    May be null.

  • referenceOptional

    string

    Synced secrets only: the source reference the target should sync from, e.g. op://Production/db/password, up to 512 characters. Omitted for a synced secret: 409 with `suggestedReference` (the reference with the vault swapped for the target environment) to confirm and send back. Ignored for a stored secret.

    Constraints: 1-512 chars

Response

201 with { secretId, created: true, changed, reference } when the target secret was created, else 200 (an equal value writes nothing: changed false); secretId is the target’s. 409 with suggestedReference for a synced secret sent without `reference`; 400 when it is already in that environment; 409 for a managed secret or a target of the other kind.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow secrets:PromoteSecret on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud secrets environments promote id --to-environment-id example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_secrets_environments_promote.