Environment object
Create, get, list, and update endpoints return this structure.
| Field | Type | Description |
|---|
id | string | Environment ID with the env_ prefix |
type | string | Always "environment" |
name | string | Environment name, up to 255 characters. It must not be empty after trimming leading and trailing whitespace |
description | string | Environment description |
config | Environment config | Normalized Environment configuration. Missing package-manager fields are added |
metadata | object | Environment metadata; defaults to {} when omitted |
archived_at | string | null | Archive time in RFC 3339 format; null while active |
created_at | string | Creation time in RFC 3339 format |
updated_at | string | Last update time in RFC 3339 format |
identity_id | string | null | Owning Forward identity. Returns the Identity ID for an Identity-owned resource, or null otherwise. See Identity ownership. |
icon_url | string | null | Icon URL associated by Forward |
binding_info | Binding info | Binding information, such as Template reference counts |
Identity ownership
An account (or Workspace) can have multiple Identities. Each Identity represents an end user of the product integrated with that account (or Workspace).
An Environment can belong to the account (or Workspace) or to an Identity. Ownership determines who can see and operate it.
Selecting ownership
| Caller | Owner | How to select |
|---|
| PAT | Account / Workspace | Omit identity_id (the default, unchanged behavior). |
| PAT | A specific Identity | Pass the query parameter identity_id=<identity_id>. |
| Admin SAT | Workspace | Resolved automatically; parameters cannot switch ownership. |
| Identity-bound SAT | The bound Identity | Resolved automatically; parameters cannot switch ownership. |
identity_id is optional and is used only for Identity-owned resources. A PAT can specify it explicitly; omitting it uses the administrator scope. With SAT, issue an Identity-scoped token and do not explicitly pass this parameter, even with an empty value. Doing so returns HTTP 400.
An Identity specified with a PAT must belong to the account or Workspace represented by that PAT and must be enabled. A nonexistent, disabled, deleted, or foreign Identity returns 404.
Ownership isolation
- Calls in the account or Workspace scope cannot see Identity-owned Environments.
- An Identity cannot see Environments owned by the account (or Workspace) itself or by other Identities in the same account.
- In a valid Identity scope (a PAT with a valid
identity_id, or an Identity SAT), cross-scope get-by-ID, update, archive, and delete operations return 404, without distinguishing a nonexistent resource from a resource owned by someone else.
- PAT calls without
identity_id and Admin SAT calls retain the existing behavior: an Owner mismatch returns 403.
Supported endpoints
Create, search, list, get, update, archive, and delete Environment endpoints support the identity_id query parameter.
GET /api/v1/forward/resources/batch does not yet support identity_id. Its visibility rules are unchanged.
Environment config
Environment runtime configuration. When omitted, it defaults to {"type":"cloud"}. When provided explicitly, it must not be null or an empty object.
| Field | Type | Required | Description |
|---|
type | string | Yes | "cloud" or "self_hosted". Defaults to cloud only when the entire config object is omitted |
packages | Environment packages | No | Preinstalled package declarations for a cloud Environment. Must not be null |
setup_script | string | No | See Environment setup script |
self_hosted config
A self_hosted Environment accepts only type and an optional setup_script. Supplying packages or another unsupported field returns 400 invalid_request_error.
{"type": "self_hosted", "setup_script": "./initialize-worker.sh"}
cloud config response shape
A cloud config response includes every reserved package-manager array under packages; undeclared arrays are returned as []. For example:
{
"type": "cloud",
"packages": {
"type": "packages",
"apt": [],
"cargo": [],
"gem": [],
"go": [],
"npm": [],
"pip": []
}
}
Environment packages
packages maps package-manager names to arrays of package specification strings. apt, npm, and pip currently install packages. cargo, gem, and go are reserved response fields and cannot currently install dependencies here.
| Key | Type | Description | Example |
|---|
type | string | Always "packages" in responses; do not supply it in requests | "packages" |
apt | array of string | Debian/Ubuntu package declarations, installed with apt-get install -y | ["git", "curl"] |
npm | array of string | Global Node.js package declarations, installed with npm install -g | ["pnpm@9"] |
pip | array of string | Python package declarations, installed with pip install | ["PyYAML==6.0.1"] |
cargo | array of string | Reserved response field; dependency installation through this field is not currently supported | [] |
gem | array of string | Reserved response field; dependency installation through this field is not currently supported | [] |
go | array of string | Reserved response field; dependency installation through this field is not currently supported | [] |
[].
Environment setup script
setup_script is a shell script run during sandbox preparation after packages installation. Use it for initialization that cannot be expressed with packages, such as cloning code, writing configuration files, or warming caches.
| Constraint | Value |
|---|
| Type | string |
| Max length | 64 KB |
| Interpreter | /bin/bash -lc |
| When it runs | Sandbox preparation, after packages installation |
| Timeout | 10 minutes |
| Nonzero exit | Fails preparation of the current sandbox |
| Repeated execution | Does not run again after succeeding in the same sandbox; runs again after the sandbox is reclaimed and rebuilt |
{
"config": {
"type": "cloud",
"setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
}
}
created_by is reserved by Forward and must not be supplied by callers (supplying it returns 400).
| Constraint | Value |
|---|
| Caller-supplied limit | Typically 15 custom key-value pairs |
| Maximum key length | 64 characters |
| Value type | string |
| Maximum value length | 512 characters |
Binding info
Reference summary included by Forward in Environment responses.
| Field | Type | Description |
|---|
agent_template_count | integer | Number of Templates currently bound to the Environment |
| Field | Type | Description |
|---|
data | array of Environment objects | Records on the current page |
has_more | boolean | Whether another page is available |
next_page | string | null | Forward cursor for the next page (recommended). Equals the current page's last_id when has_more=true; otherwise null |
first_id | string | null | ID of the first record on the current page |
last_id | string | null | ID of the last record on the current page |
page, after_id, and before_id are mutually exclusive; providing more than one returns 400. Use page where possible; it has the same semantics as after_id.
