togglddocs
Dashboard
GuidesAPI reference
Environments

Create an environment

POST
/api/v1/environments

Creates an environment and its public token. The new environment goes last in the workspace order. Every existing flag gets a copy of its values from the environment before it, but starts off, with no targeting rules. Later changes in that environment do not affect the copy.

Requires a management key.

Returns 409 if the key is already in use.

Authorization

bearer
headerAuthorizationBearer <token>

Send a credential in the Authorization header: Authorization: Bearer <token>. Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.

  • Management key (ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can.
  • Evaluation key (ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry.
  • Public token (ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.

Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.

Request Body

application/json
  1. body

The environment to create. It goes last in the workspace order.

isProduction?|

Whether the environment serves production traffic. Defaults to false.

color?|

The environment's display color in the dashboard. Defaults to gray.

key*string

The environment key, unique in the workspace, such as staging.

Length1 <= length
name*string

A display name for the environment.

Length1 <= length

Response Body

Created

application/json
  1. response

A deployment stage in a workspace, such as development or production. Each environment has its own flag values, enabled states, and targeting rules. Every API key belongs to one environment.

id*string

The environment ID, such as env_….

tenantId*string

The ID of the workspace that owns the environment.

isProduction?|

Whether the environment serves production traffic.

position*integer

The environment's place in the workspace order, ascending. The dashboard lists environments in this order. A new environment goes last and copies flag values from the environment before it.

Range-9007199254740991 <= value <= 9007199254740991
color?|

The environment's display color in the dashboard. Defaults to gray.

key*string

The environment key, unique in the workspace, such as production.

name*string

A display name for the environment.

createdAt*string

When the environment was created, as an ISO 8601 timestamp.

Example Request
curl -X POST 'https://api.toggld.io/api/v1/environments' \  -H 'Content-Type: application/json' \  -d '{  "key": "staging",  "name": "Staging",  "color": "amber"}'
Example Response
{  "id": "env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b",  "tenantId": "t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e",  "isProduction": true,  "position": 1,  "color": "red",  "key": "production",  "name": "Production",  "createdAt": "2026-05-01T12:00:00.000Z"}

List environments GET

Returns every environment in the workspace, in workspace order (ascending `position`). Requires a management key.

Update an environment PATCH

Changes the key, name, color, or production setting of an environment. Omitted fields keep their current values. To change the order of environments, use the reorder environments endpoint. Requires a management key. Returns `404` if the environment does not exist and `409` if the new key is already in use.