1. Docs
  2. API Reference
  3. Create a new Environment in an Application

Create a new Environment in an Application

POST/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments

Authentication

  • Bearer Token Authorization

    JWT access token

Request body

  • namestring*

    Display name for the new Environment

  • slugstring

    URL-safe slug. Lowercase alphanumeric with optional dashes (no leading/trailing dash). Auto-derived from `name` when omitted. Unique within the Application.

  • copy_fromstring

    Source env slug to clone configuration from. Copies permissions, roles, role-permission joins, hierarchy nodes, OAuth client configs (without secrets), and webhook configs (without secrets). Identities and role assignments are NOT copied.

Code samples

cURLJavaScriptPythonGo
curl -X POST "https://api.canopy.dev/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "slug": "string",
    "copy_from": "string"
  }'

Responses

201 Environment created. When `copy_from` is set, permissions/roles/role-permission joins/hierarchy nodes/OAuth client configs (without secrets)/webhook configs (without secrets) are cloned from the source env. Identities and role assignments are NOT copied.
{
  "environment": {
    "id": "string",
    "application_id": "string",
    "name": "string",
    "slug": "string",
    "settings": {},
    "version": 0,
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  },
  "oauth_client_rotations": [
    {
      "source_client_id": "string",
      "client_id": "string",
      "client_secret": "string"
    }
  ],
  "webhook_subscription_rotations": [
    {
      "id": "string",
      "url": "string",
      "secret": "string"
    }
  ]
}

application/json

  • environmentEnvironmentResponseDto*
  • oauth_client_rotationsOAuthClientRotationResponseDto[]*
  • webhook_subscription_rotationsWebhookSubscriptionRotationResponseDto[]*
401 Invalid or expired token
403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)
409 An Environment with this slug already exists in the Application

Returned object

On this page

Related endpoints

GETList Environments in an Application
GETGet a single Environment by slug
PATCHRename or re-slug an Environment
DELETEDelete an Environment
GETExport an Environment's configuration as JSON
POSTReplace an Environment's configuration from a JSON payload (destructive)
GETGet the Environment's access model
PUTSwitch the Environment's access model
GETGet hierarchy schema for the active Environment
PATCHUpdate hierarchy schema for the active Environment
POSTRevert this Environment from hierarchy to flat