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.

{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}

• Create an environment
• Get an environment
• Delete an environment

Creates an environment in the team’s default project. No API key is created alongside it, so mint one separately.

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

{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}

• 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.

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

curl --request GET \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN"

{
  "object": "environment",
  "id": "environment_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "alice-app-preview",
  "client_id": "client_01JN22VQ4FZY3K0NGY18EPZFV4"
}

• 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.

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.

curl --request DELETE \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN"

• 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.