Set environment variables with the Apps API

Environment variables give an app its settings and secrets, such as a database address or a key for another service. Each variable reaches the build, the running app or both. Once you save a value, the API never shows it again.

The Apps API sets the variables of the all environment, which the dashboard shows as All environments on the Variables tab of the app's page under App Deployment. Every release reads them, unless production, previews or a branch have a value of their own for the same name (Environments and variables). Values for one environment, .env files and env groups are set on that tab or through the deployments API. This page covers the Apps API, which scripts written for Apps keep using.

• Send your access token as Authorization: Bearer $CORITAN_TOKEN (Authentication). Each request takes the app's uuid, which GET /api/v1/client/apps lists.
• For an organization's app, you need the owner or admin role in the organization to change variables, and every member can read their names. Send the same requests under /api/v1/orgs/{org_slug}/apps (organization apps reference).
• A change reaches the app with its next release (Apply a change).

A name has upper-case letters, digits and underscores, does not start with a digit, and has at most 128 characters, such as DATABASE_URL. These names are set by the platform, so you cannot use them:

• PORT, TZ, STARTUP, SERVER_MEMORY, SERVER_IP and SERVER_PORT
• any name that starts with CORITAN_ or P_SERVER_, except the three names in Names your app reads

A value can be empty, and holds up to 32 KiB. An app has up to 200 variables, and their names and values together hold up to 256 KiB.

Each variable has a target:

both

The build and every replica get it. New variables have this target unless you choose another.

runtime

Only the replicas get it.

build

Only the build gets it, as an environment variable of the install and build commands (Builds).

An image app is not built, so only the variables its replicas get reach it. Every replica also gets PORT, CORITAN_APP, CORITAN_REGION and CORITAN_DEPLOYMENT (What your app must do).

Three names that start with CORITAN_ are ones the platform never sets. Your own app reads them when it runs, so you can set them:

The platform does not set or read these names. Your app decides what each holds.

Set each one with the target runtime. The build leaves out every name that starts with CORITAN_, so a value with the target build or both never reaches it, and a build cannot read these three. Like any new variable, each is secret unless you say otherwise. A change reaches the app with its next release, so redeploy after you set one (Apply a change).

Every other name that starts with CORITAN_, such as CORITAN_REGION, and every name that starts with P_SERVER_, stays refused.

A variable is secret unless you say otherwise. A secret value of six characters or more appears as [redacted] in the build log. A plain value can appear in the build log as it is.

Both kinds are stored encrypted, and neither is ever shown again after you save it. For a value of eight characters or more, the variable shows its last four characters as hint, so you can tell which value is saved. To change a value, replace it.

Replicas keep the variables they started with. After you change a variable:

• For one that the running app reads, redeploy the app.
• For one that the build reads, such as a build-time NEXT_PUBLIC_ value, rebuild the app, so the build runs again.

Redeploy and Rebuild show both. The answer to each change says redeploy_required when a new release is needed.

Rarely, a saved value can no longer be opened on the platform, and the variable's readable is false. The running app starts without it, and a build that needs it fails with The build variable API_KEY cannot be read on this platform. Save it again. Set the variable again with its value.

In each request, target is both, runtime or build.

GET /api/v1/client/apps/{app_uuid}/env lists the variables by name, without their values:

curl https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21/env \
  -H "Authorization: Bearer $CORITAN_TOKEN"

{
  "vars": [
    {
      "key": "DATABASE_URL",
      "secret": true,
      "target": "runtime",
      "value": null,
      "hint": "shop",
      "readable": true,
      "created_at": "2026-09-20T09:12:00Z",
      "updated_at": "2026-09-24T16:40:00Z"
    },
    {
      "key": "NODE_ENV",
      "secret": false,
      "target": "both",
      "value": null,
      "hint": null,
      "readable": true,
      "created_at": "2026-09-20T09:12:00Z",
      "updated_at": "2026-09-20T09:12:00Z"
    }
  ]
}

value is always null. hint is the last four characters of a value of eight characters or more, and null otherwise. readable is false when the saved value can no longer be opened.

PUT /api/v1/client/apps/{app_uuid}/env/{key} creates the variable or changes it. The body takes value, secret and target. A new variable needs value. For one that exists, leave value out to keep the saved value while you change secret or target. A name cannot change: to rename a variable, delete it and set it again.

curl -X PUT https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21/env/STRIPE_KEY \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "sk_live_EXAMPLE0000", "target": "runtime"}'

{
  "var": {"key": "STRIPE_KEY", "secret": true, "target": "runtime", "value": null, "hint": "0000", "readable": true},
  "created": true,
  "redeploy_required": true
}

created is true for a new variable. The example shortens var.

PUT /api/v1/client/apps/{app_uuid}/env sets up to 200 variables in one request. Each item in vars has a key and the same value, secret and target as above. With "replace": true, every variable not in the list is deleted.

curl -X PUT https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21/env \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vars": [{"key": "NODE_ENV", "value": "production", "secret": false}, {"key": "DATABASE_URL"}], "replace": true}'

{
  "created": [],
  "updated": ["NODE_ENV"],
  "deleted": ["STRIPE_KEY"],
  "redeploy_required": true
}

created, updated and deleted name the variables the request touched. DATABASE_URL kept its value because the request left value out. The answer also holds vars, every variable after the change, as in the list above. "replace": true deletes only variables of the all environment: values for one environment or branch stay.

DELETE /api/v1/client/apps/{app_uuid}/env/{key} deletes one variable and answers {"deleted": "STRIPE_KEY", "redeploy_required": true}. Running replicas keep it until the next release, and the value cannot be recovered.

GET /api/v1/client/apps/{app_uuid}/env lists each name with its target, whether it is secret, and the hint of its value. The next release uses them.

'database_url' is not a variable name: upper-case letters, digits and underscores, not starting with a digit, at most 128 characters

Change the name, for example to DATABASE_URL.

PORT is set by the platform and cannot be changed

The platform sets that name on every replica. Use another name, and read PORT to know where to listen. The same message appears for CORITAN_REGION and any other name that starts with CORITAN_, except CORITAN_ORG_API_KEY, CORITAN_WEBHOOK_SECRET and CORITAN_MICROSOFT_ADS_FEED_URL.

A CORITAN_ variable is empty during the build

The build leaves out every name that starts with CORITAN_. Set CORITAN_ORG_API_KEY, CORITAN_WEBHOOK_SECRET or CORITAN_MICROSOFT_ADS_FEED_URL with the target runtime and read it from the running app.

The environment is larger than 256 KiB in total

Shorten or delete some values. A large file is better kept in Object Storage and fetched when the app starts.

A variable does not change in the running app

Replicas keep the variables they started with. Redeploy the app, or rebuild it for a variable the build reads. A value that production or a branch sets for the same name also wins over the one the Apps API sets.

• Deploy an app with the Apps API
• How the Apps API runs an app
• Apps API limits
• Environments and variables, for environments, .env files and env groups