<!-- llms.txt: https://workos.com/llms.txt -->

# Environment

An environment is a single deployment of a user's app, with its own users, configuration, and API keys. Environments created through the Platform API have AuthKit enabled and IdP-initiated SSO allowed.

:::code-group{title="Example Environment"}

```json language="curl"
{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}
```

:::

## Endpoints

- [Create an environment](https://workos.com/docs/reference/platform/environment/create)
- [Get an environment](https://workos.com/docs/reference/platform/environment/get)
- [Delete an environment](https://workos.com/docs/reference/platform/environment/delete)

## Create an environment

Creates an environment in the team's default project. No API key is created alongside it, so [mint one](https://workos.com/docs/reference/platform/api-key/create) separately.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "alice-app-preview",
        "production": false
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}
```

:::

### Error responses

- **403** (`platform_not_authorized`): the platform isn't authorized on this team.
- **404** (`team_not_found`): no such team.
- **422** (`production_environment_requires_billing`): `production` was `true` but the team's `production_state` isn't `Active`. A team admin must add billing in the WorkOS Dashboard first.

## Delete an environment

Deletes a sandbox environment that the calling platform created, and returns `204 No Content`. Use it to clean up ephemeral environments so a user's dashboard doesn't fill with dead preview deployments.

Deletion is deliberately narrow. Production environments, a team's default environments, and environments created by anyone else all refuse.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN"
```

:::

### Error responses

- **403** (`production_environment_cannot_be_deleted`): the environment is a production environment.
- **403** (`environment_not_created_by_platform`): the calling platform didn't create this environment.
- **404** (`team_not_found`, `environment_not_found`): no such team or environment, or the platform's access has been revoked.

## Get an environment

Returns an environment, and doubles as a health check on the platform's access to it.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request GET \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN"
```

```json language="json" title="Response" tab="2"
{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}
```

:::

### Error responses

- **404** (`environment_not_found`): the environment doesn't exist, belongs to another team, or the platform's access has been revoked.
- **404** (`team_not_found`): no such team.

### environment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "environment" | Yes | The object type. |
| `id` | string | Yes | Unique identifier of the environment. |
| `name` | string | Yes | The name of the environment. |
| `client_id` | string | Yes | The client ID the environment's app uses to start an AuthKit session. |

### POST /platform/teams/:team_id/environments

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team to create the environment in. |
| `name` | string | Yes | The name of the environment. |
| `production` | boolean | No | Whether to create a production environment instead of a sandbox. Requires the team's `production_state` to be `Active`. Defaults to `false`. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `environment` | object | The created environment. |

### DELETE /platform/teams/:team_id/environments/:environment_id

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team the environment belongs to. |
| `environment_id` | string | Yes | The ID of the environment to delete. |

### GET /platform/teams/:team_id/environments/:environment_id

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team the environment belongs to. |
| `environment_id` | string | Yes | The ID of the environment. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `environment` | object | The environment. |