What is an environment?
An environment is a named deployment context within a project. Typical environments are production, staging, and development, but you can create any environments your workflow requires.
All flags and environment-scoped API keys belong to a specific environment. When you evaluate a flag from your application, you identify the target environment using its key.
The key field
The key field is a short, stable identifier you define at creation time — for example, production or staging. You pass this value as environment_key in evaluation requests:
{
"flag_key": "new-dashboard",
"environment_key": "production",
"context": {
"user_id": "user-123"
}
}
The key is set at creation and cannot be changed. Choose a value that is stable and meaningful to your deployment pipeline.
Region assignment
When you create an environment, Togul automatically assigns it to the current region. In a multi-region deployment:
- The primary region is assigned automatically on creation.
- For evaluation requests originating from a non-primary region, the environment must be explicitly enabled for that region.
- If an environment is not enabled for the requesting region, evaluation requests return a
403 Forbidden response.
Region assignments are managed separately from the environment itself.
Cascade deletion
Deleting an environment permanently removes all of its dependent resources:
- Flags (and their rules)
- Environment-scoped API keys
- Region assignments
- Queued evaluation events
Environment deletion is permanent and cascades to all flags, API keys, and region assignments within that environment.
Environment schema
| Field | Type | Description |
|---|
id | UUID | Unique environment identifier |
project_id | UUID | The project this environment belongs to |
key | string | Short identifier used in evaluation requests |
name | string | Display name |
description | string | Optional description (nullable) |
created_at | datetime | ISO 8601 creation timestamp |
updated_at | datetime | ISO 8601 last-updated timestamp |
Endpoints
| Method | Endpoint | Permission | Description |
|---|
GET | /api/v1/projects/{project_id}/environments | Authenticated | List environments in a project |
POST | /api/v1/projects/{project_id}/environments | environments.write | Create a new environment |
GET | /api/v1/projects/{project_id}/environments/{id} | environments.read | Get a single environment |
DELETE | /api/v1/projects/{project_id}/environments/{id} | environments.delete | Delete an environment and its resources |