secrets.environments.create

Add an environment

POST /secrets/api/environmentsIAM secrets:CreateSecretEnvironmentChanges state

Request syntax

POST /secrets/api/environments
{
  "slug": "string",
  "name": "string",
  "position": "number",
  "color": "enum"
}

Request body

  • slugRequired

    string

    Short id of the environment, e.g. qa: lower-case letters, digits and hyphens, starting with a letter or digit, at most 63 characters. Unique in the organization (an existing slug is refused with 409) and cannot be changed later. Workflow jobs name an environment by it.

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

  • nameRequired

    string

    Display name, e.g. QA. 1 to 64 characters.

    Constraints: 1-64 chars

  • positionOptional

    number

    Place in the promotion order, 0 to 10000; a higher number is later (Development 10, Staging 20, Production 30 to start with). Omitted: the last environment’s position plus 10.

    Constraints: integer, 0-10000

  • colorOptional

    enum

    The dot shown beside the environment: gray, blue, teal, green, amber, red or violet. Null: automatic (from the slug).

    One of: gray, blue, teal, green, amber, red, violet

    May be null.

Response

201 with the environment: id, slug, name, position, color, effectiveColor, createdAt. 409 when the slug exists or the environments quota is full.

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:CreateSecretEnvironment 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 create --slug example --name 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_create.