# Environment variables

A project's variables per environment: list, add, change, delete and restore them, reveal one, or pull them all.

Source: https://docs.orbits.africa/api/environment-variables

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](https://docs.orbits.africa/deploy/environment-variables).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/env`: List variables
- `POST /v1/teams/{team}/projects/{project}/env`: Add variables, or import a .env file
- `PATCH /v1/teams/{team}/projects/{project}/env/{key}`: Change a value or its environments
- `DELETE /v1/teams/{team}/projects/{project}/env/{key}`: Delete a variable
- `POST /v1/teams/{team}/projects/{project}/env/{key}/restore`: Undo a delete
- `POST /v1/teams/{team}/projects/{project}/env/{key}/reveal`: Reveal a value
- `POST /v1/teams/{team}/projects/{project}/env/pull`: Download values for local development (`orbits env pull`)

## The environment variable object



- `id` (string, required)
- `key` (string, required)
- `value` (string or null, required): Only 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_KEY` suffix). Otherwise null; use `POST .../env/{key}/reveal`.
- `sensitive` (boolean, required)
- `environments` (array of string, required)
- `pending_redeploy` (boolean, required): Changed since the latest deployment; shows the "New" tag.
- `created_at` (string, required)
- `updated_at` (string, required)
- `updated_by` (object, required)
  - `id` (string, required)
  - `name` (string, required)
## List variables

```http
GET /v1/teams/{team}/projects/{project}/env
```

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.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string)
- `environment` (string): Only variables that apply to this environment. One of `production`, `preview`, `development`.
- `q` (string): Substring of the key.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "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
  }
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Add variables, or import a .env file

```http
POST /v1/teams/{team}/projects/{project}/env
```

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.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `variables` (array of object, required): At most 500 items.
  - `key` (string, required): At most 255 characters.
  - `value` (string, required): May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on `EnvVar.value`. At most 32768 characters.
  - `environments` (array of string): Used by Production and Preview unless the user picks otherwise.
  - `sensitive` (boolean): Write-only: nobody can read the value back, only replace it. Defaults to `true`.
- `on_conflict` (string): `fail` (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 to `fail`.

Example:

```sh
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
      }
    ]
  }'
```

Response `201`:

```json
{
  "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
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Change a value or its environments

```http
PATCH /v1/teams/{team}/projects/{project}/env/{key}
```

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.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `key`

Body:

- `value` (string): At most 32768 characters.
- `environments` (array of string)

Example:

```sh
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"
    ]
  }'
```

Response `200`:

```json
{
  "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
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Delete a variable

```http
DELETE /v1/teams/{team}/projects/{project}/env/{key}
```

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.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `key`

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "key": "key",
  "restorable_until": "2026-11-10T09:30:00Z",
  "redeploy_required": false
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Undo a delete

```http
POST /v1/teams/{team}/projects/{project}/env/{key}/restore
```

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.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `key`

Example:

```sh
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)"
```

Response `200`:

```json
{
  "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
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Reveal a value

```http
POST /v1/teams/{team}/projects/{project}/env/{key}/reveal
```

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

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `key`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/reveal" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "key": "key",
  "value": "value"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Download values for local development (`orbits env pull`)

```http
POST /v1/teams/{team}/projects/{project}/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.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `environment` (string, required): One of `production`, `preview`, `development`.

Example:

```sh
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"
  }'
```

Response `200`:

```json
{
  "environment": "production",
  "variables": {},
  "skipped_sensitive": [
    "skipped-sensitive"
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
