API reference · DeployEnvironment variables
Environment variables
A project's variables per environment: list, add, change, delete and restore them, reveal one, or pull them all.
Each variable is a key with a value for one or more environments (production, preview, development). Values are encrypted at rest and never returned by a list: reveal one, or pull an environment's, with a full token. A read token never reads values. A change applies to deployments created after it: redeploy to use it. See Environment variables.
The environment variable object
Fields
idstringrequiredkeystringrequiredvaluestring or nullrequiredOnly for a non-sensitive variable whose key is meant for the browser (
NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_,VITE_,REACT_APP_,EXPO_PUBLIC_prefix, or a_PUBLIC_KEYsuffix). Otherwise null; usePOST .../env/{key}/reveal.sensitivebooleanrequiredenvironmentsarray of stringrequiredpending_redeploybooleanrequiredChanged since the latest deployment; shows the "New" tag.
created_atstringrequiredupdated_atstringrequiredupdated_byobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
List variables
The Environment variables page: one row per key, with the environments it applies to. Values are encrypted at rest. A row's value is returned only for a variable that is not sensitive and whose key is meant for the browser (it starts with NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_ or EXPO_PUBLIC_, or ends with _PUBLIC_KEY); every other value is null and the page shows dots. A sensitive variable can never be read back by anyone (the dialog says "Nobody can read it back, only replace it"), so show no eye icon, Reveal value or Copy value for it. For any other variable, "Reveal value" and "Copy value" call POST /v1/teams/{team}/projects/{project}/env/{key}/reveal.
total is the number of variables that match the filters ("10 variables"). last_changed feeds the pull dialog ("Last changed yesterday by Shady Asaolu"); it is null when there are none. redeploy drives the blue banner ("You changed 1 variable. Redeploy so production picks it up."): required is true when something changed since the project's latest deployment and changed counts those variables; each row's pending_redeploy marks the ones to highlight (the "New" tag). Until deployments exist, redeploy.required is always false.
Permissions: Any team member, including viewers. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.cursorstringenvironmentstringOnly variables that apply to this environment.
One of
production,preview,development.qstringSubstring of the key.
Response 200
Variables.next_cursorstring or nullitemsarray of EnvVarrequiredShow 9 child fieldsHide child fields
idstringrequiredkeystringrequiredvaluestring or nullrequiredOnly for a non-sensitive variable whose key is meant for the browser (
NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_,VITE_,REACT_APP_,EXPO_PUBLIC_prefix, or a_PUBLIC_KEYsuffix). Otherwise null; usePOST .../env/{key}/reveal.sensitivebooleanrequiredenvironmentsarray of stringrequiredpending_redeploybooleanrequiredChanged since the latest deployment; shows the "New" tag.
created_atstringrequiredupdated_atstringrequiredupdated_byobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
totalintegerrequiredVariables matching the filters.
last_changednull or objectrequiredShow 2 child fieldsHide child fields
atstringrequiredbyobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
redeployobjectrequiredShow 2 child fieldsHide child fields
requiredbooleanrequiredchangedintegerrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"next_cursor": null,
"items": [
{
"id": "var_01J9ZK3Q",
"key": "key",
"value": null,
"sensitive": false,
"environments": [
"production"
],
"pending_redeploy": false,
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z",
"updated_by": {
"id": "id",
"name": "my-app"
}
}
],
"total": 1,
"last_changed": {
"at": "2026-11-10T09:30:00Z",
"by": {
"id": "id",
"name": "my-app"
}
},
"redeploy": {
"required": false,
"changed": 1
}
}Add variables, or import a .env file
Saves one or more variables. The Add variable dialog sends one with the default on_conflict: fail: a key that already exists is 409 and nothing is saved (use Edit instead). The Import .env dialog sends every parsed line with on_conflict: replace, which replaces the value and environments of keys that already exist, as its warning says ("Importing replaces its value in the environments you pick"). The dialog parses the file in the browser; show the conflicts from the list you already loaded. sensitive defaults to true, as the Sensitive checkbox does.
A project can have at most 1,000 variables. An import that would go over (replacing existing keys adds none) is 422 on variables and saves nothing. The request body is at most 1 MiB, which the gateway enforces on every request (413), so a very large import must be split.
The new values apply to deployments created afterwards; redeploy_required says whether the banner should show.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonvariablesarray of objectrequiredAt most 500 items.
Show 4 child fieldsHide child fields
keystringrequiredAt most 255 characters.
valuestringrequiredMay be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on
EnvVar.value.At most 32768 characters.
environmentsarray of stringUsed by Production and Preview unless the user picks otherwise.
sensitivebooleanWrite-only: nobody can read the value back, only replace it.
Defaults to
true.
on_conflictstringfail(Add variable): a key that already exists is 409 and nothing is saved.replace(Import .env): existing keys get the new value and environments.One of
fail,replace. Defaults tofail.
Response 201
Saved.itemsarray of EnvVarrequiredShow 9 child fieldsHide child fields
idstringrequiredkeystringrequiredvaluestring or nullrequiredOnly for a non-sensitive variable whose key is meant for the browser (
NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_,VITE_,REACT_APP_,EXPO_PUBLIC_prefix, or a_PUBLIC_KEYsuffix). Otherwise null; usePOST .../env/{key}/reveal.sensitivebooleanrequiredenvironmentsarray of stringrequiredpending_redeploybooleanrequiredChanged since the latest deployment; shows the "New" tag.
created_atstringrequiredupdated_atstringrequiredupdated_byobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
createdintegerrequiredreplacedintegerrequiredredeploy_requiredbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"variables": [
{
"key": "STRIPE_SECRET_KEY",
"value": "value",
"environments": [
"production"
],
"sensitive": true
}
]
}'{
"items": [
{
"id": "var_01J9ZK3Q",
"key": "key",
"value": null,
"sensitive": false,
"environments": [
"production"
],
"pending_redeploy": false,
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z",
"updated_by": {
"id": "id",
"name": "my-app"
}
}
],
"created": 1,
"replaced": 1,
"redeploy_required": false
}Change a value or its environments
The Edit dialog: the key is read-only ("To rename a key, add a new one and delete this one"). Send value only when the user typed a new one; leave it out to change just the environments. Send environments only when the checkboxes changed. At least one of them is required. Whether a variable is sensitive cannot be changed here.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.keystringrequired
Body
application/jsonvaluestringAt most 32768 characters.
environmentsarray of string
Response 200
Saved.itemEnvVarrequiredShow 9 child fieldsHide child fields
idstringrequiredkeystringrequiredvaluestring or nullrequiredOnly for a non-sensitive variable whose key is meant for the browser (
NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_,VITE_,REACT_APP_,EXPO_PUBLIC_prefix, or a_PUBLIC_KEYsuffix). Otherwise null; usePOST .../env/{key}/reveal.sensitivebooleanrequiredenvironmentsarray of stringrequiredpending_redeploybooleanrequiredChanged since the latest deployment; shows the "New" tag.
created_atstringrequiredupdated_atstringrequiredupdated_byobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
redeploy_requiredbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"value": "value",
"environments": [
"production"
]
}'{
"item": {
"id": "var_01J9ZK3Q",
"key": "key",
"value": null,
"sensitive": false,
"environments": [
"production"
],
"pending_redeploy": false,
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z",
"updated_by": {
"id": "id",
"name": "my-app"
}
},
"redeploy_required": false
}Delete a variable
The Delete dialog ("Type STRIPE_SECRET_KEY to confirm"; the typed confirmation is checked in the browser). The variable is hidden at once but its encrypted value is kept until restorable_until (10 minutes), so the toast's Undo can call POST /v1/teams/{team}/projects/{project}/env/{key}/restore. Deployments created after the delete no longer get it.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.keystringrequired
Response 200
Deleted, and restorable untilrestorable_until.keystringrequiredrestorable_untilstringrequiredredeploy_requiredbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"key": "key",
"restorable_until": "2026-11-10T09:30:00Z",
"redeploy_required": false
}Undo a delete
The Undo button on the "deleted" toast. It brings the variable back with the value and environments it had. 404 means the 10 minutes have passed (or it was never deleted); 409 means a variable with that key exists again.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.keystringrequired
Response 200
Restored.itemEnvVarrequiredShow 9 child fieldsHide child fields
idstringrequiredkeystringrequiredvaluestring or nullrequiredOnly for a non-sensitive variable whose key is meant for the browser (
NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_,VITE_,REACT_APP_,EXPO_PUBLIC_prefix, or a_PUBLIC_KEYsuffix). Otherwise null; usePOST .../env/{key}/reveal.sensitivebooleanrequiredenvironmentsarray of stringrequiredpending_redeploybooleanrequiredChanged since the latest deployment; shows the "New" tag.
created_atstringrequiredupdated_atstringrequiredupdated_byobjectrequiredShow 2 child fieldsHide child fields
idstringrequirednamestringrequired
redeploy_requiredbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/restore" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"item": {
"id": "var_01J9ZK3Q",
"key": "key",
"value": null,
"sensitive": false,
"environments": [
"production"
],
"pending_redeploy": false,
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z",
"updated_by": {
"id": "id",
"name": "my-app"
}
},
"redeploy_required": false
}Reveal a value
"Reveal value" and "Copy value" (and the eye icon) on a row. It is a POST because every reveal is recorded as a project.env.revealed event with who asked and which key, never the value. A sensitive variable answers 409: it can never be read back. The response is never cached or replayed: this call ignores Idempotency-Key, so every call reads the value again and is recorded.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.keystringrequired
Response 200
The value.keystringrequiredvaluestringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/reveal" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"key": "key",
"value": "value"
}Download values for local development (orbits env pull)
What orbits env pull calls to write .env.local. It returns the values of every variable that applies to environment, except sensitive ones, which nobody can read back: their keys are listed in skipped_sensitive so the CLI can tell the user. Every pull is recorded as a project.env.pulled event. The response is never cached or replayed: this call ignores Idempotency-Key, so every call reads the values again and is recorded. The dashboard only shows the pull dialog; it does not call this endpoint.
Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonenvironmentstringrequiredOne of
production,preview,development.
Response 200
Values for the environment.environmentstringrequiredOne of
production,preview,development.variablesobjectrequiredskipped_sensitivearray of stringrequiredKeys left out because nobody can read them back.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/pull" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"environment": "production"
}'{
"environment": "production",
"variables": {},
"skipped_sensitive": [
"skipped-sensitive"
]
}