Environment variables

An environment variable is a named value you define once for your organization and then reference from workflow content as {{env.KEY}}. Each variable holds a separate value for each environment, so the same workflow resolves a Development URL in Development and a Production URL in Production, with no edit when you promote it.

Typical uses are a base URL for button links, a support address, or an API token for an HTTP request step.

Create a variable

In the dashboard, open Variables in the Developer group of the sidebar and choose Create variable.

• Variable key. Must start with a letter and contain only letters, digits and underscores, up to 256 characters. Keys are case sensitive; the convention is upper case, such as BASE_URL.
• Values. One input per environment. A value can be up to 256 characters, and the dashboard requires a value for every environment on a new variable.

The page lists your variables with their value in each environment and when they were last updated, and its search box filters them by key.

The dashboard Variables page is available on Pro and above; on the Free plan it shows an upgrade prompt instead of the list. See Plans and limits.

Use a variable in a workflow

Reference the key under the env namespace in any step content that accepts variables:

Open your dashboard: {{env.BASE_URL}}/billing

The value for the environment the workflow runs in is substituted when the message is rendered, both in the dashboard preview and when a real notification is delivered.

Built-in variables

Two variables exist in every environment and cannot be edited. They are listed at the top of the Variables page:

A custom variable with the key name or type is overridden by the built-in one, so pick another key.

Secrets

A variable is marked secret by setting isSecret when you create it. Changing isSecret later needs a dashboard session or a non-API-key credential: an update that carries isSecret, key or type returns 403 under an environment-scoped API key (see the REST API section). Secret values are encrypted at rest and returned as •••••••• by every read endpoint.

A secret resolves to its real value only in server-side steps that need to authenticate: HTTP request steps and Custom (code-defined) steps. In every channel step (email, SMS, push, chat, in-app) a secret stays masked, so its plaintext cannot reach a subscriber or show up in the activity feed.

When you edit a secret variable, leave an environment's input blank to keep its stored value. The API rejects the masked placeholder if you send it back as a value.

Edit and delete

Renaming a key changes what {{env.KEY}} means, so check where a variable is used first. GET /v1/environment-variables/{variableKey}/usage returns the workflows whose step controls reference it, and the dashboard shows the same list in the Delete variable confirmation.

Limits

By default an organization can hold up to 10 variables. Creating another returns a 400 whose body reports the current count and the limit.

REST API

The same operations are available under /v1/environment-variables, authenticated with an ApiKey like the rest of the REST API. Each operation has a page in the API reference, and they are in the OpenAPI document under the Environment Variables tag.

Create a variable with a value for each environment, identified by environment ID:

curl -X POST https://api.notifly.io/v1/environment-variables \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "BASE_URL",
    "isSecret": false,
    "values": [
      { "_environmentId": "<development-environment-id>", "value": "https://dev.example.com" },
      { "_environmentId": "<production-environment-id>", "value": "https://app.example.com" }
    ]
  }'

• A duplicate key returns 409.
• On update, values are merged by environment ID: an environment you leave out keeps its stored value.
• An API key is scoped to one environment. It sees only that environment's values when it reads, and it can only write a value for its own environment (a different _environmentId returns 403). An API key also cannot change a variable's key, type or isSecret on update (403); use a dashboard session for that, or to set values for every environment at once.