> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Global Environment: project-wide configuration for your code
- URL: https://blog.protokol.io/global-environment/
- Published: 2026-11-17T17:33:09.000Z
- Updated: 2026-11-17T18:14:12.000Z
- Description: The global environment keeps project-wide values in one place and exposes them as $globalEnv, with groups, $globalEnv.group(), and per-identity access to encrypted values.
- Author: Strahinja Djuric
- Tags: Engineering

Most projects have a handful of values that many pieces of code need: a webhook URL, a partner API base address, a feature setting. Copying them into every function and workflow means editing many places when one changes. The **global environment** keeps them in one place for the whole project. You manage it in the dashboard under Developer › Global Environment, and your code reads it as `$globalEnv`.

## What it is

Global env is the project-level set of key-value pairs behind `$globalEnv`. It is separate from a platform function's own `$env`, which holds variables for that one function and one environment. Use `$env` for what belongs to a single function, and `$globalEnv` for what the project shares.

A value can be a plain value or an encrypted one. Plain values are what you use for URLs, names and settings.

## Reading values

Every key sits at the top level of `$globalEnv`:

```js
const webhookSecret = $globalEnv.WEBHOOK_SECRET

```

The same object is available in platform functions, and in workflow expressions:

```js
const stripeKey = $globalEnv.STRIPE_SECRET_KEY;

```

Component function code also reads `$globalEnv`.

## Groups

A global env can be split into **groups**. A group is its own set of keys, which lets you organize values (for example, everything for payments in a `payments` group) and give a group its own access rules. The default group is called `"default"`.

Two things to know about how groups look from code:

- Every group's keys appear at the top level of `$globalEnv`, with no group name in the path. A key in the `payments` group is still `$globalEnv.STRIPE_SECRET_KEY`.
- A key name lives in one group only, so groups never overwrite each other.

To read one group, call `$globalEnv.group(name)`:

```js
const stripeKey = $globalEnv.group("payments").STRIPE_KEY

```

`group()` returns a plain object with that group's keys, the same values the run sees at the top level. An unknown group returns `{}`. The `group` method does not show up in `Object.keys($globalEnv)`, in JSON, or in a spread, so enumerating the object only gives you your values.

`group` is a reserved key name, so you can't create a new key called `group`. An existing key with that name keeps its value, but until it is renamed, that project's code has no `group()` method.

## Where it is available

| Where                                                    | $globalEnv                                |
| -------------------------------------------------------- | ----------------------------------------- |
| Platform functions (authenticated calls)                 | Available                                 |
| Public platform functions                                | Not available                             |
| Component functions                                      | Available                                 |
| Workflow expression nodes                                | Available                                 |
| Workflow condition and switch nodes                      | No                                        |
| Workflow dry runs and integration node expression inputs | Plain values only; never encrypted values |

Two details worth a closer look:

- **Public functions get no `$globalEnv`.** Public functions are called without authentication, and `$globalEnv` (like `$initiator`) is not available to them. Give such a function its own `$env` variables instead.
- **Condition and switch nodes get no `$globalEnv`.** They decide from their input only, with no token and no way to reach the platform.

## Encrypted values

Global env can also hold secrets (see our [secrets post](https://blog.protokol.io/secrets/)): encrypted, write-only values that are never shown again once saved. They use the same value prefixes as function env (`secret::`, `secretgen::`, `secretref::`, `literal::`). In the dashboard an encrypted value shows as `Encrypted`.

![Global environment page showing a payments group: PAYMENT_API_URL as a plain value, PAYMENT_API_KEY listed as Encrypted](https://blog.protokol.io/content/images/2026/11/01-payments-group.png)  
*A `payments` group with a plain URL and an encrypted key. The encrypted value is write-only and shows only as Encrypted.*

The important point for your code is who gets them. An encrypted global value reaches a run only when the identity the code runs as (see [run identities](https://blog.protokol.io/run-identities/)) holds `secrets::read global_env` (or `secrets::read global_env.<group>` for one group's values). Without that, the run still gets the plain values, and the encrypted keys are left out. Check for a key before you use it.

Changing secrets takes `manage global_env` plus `secrets::write global_env`, or `secrets::write global_env.<group>` for a group. Changing plain values needs only the resource's own permission. The full rules, limits and refusals are on the security model page, linked below.

## A worked example: payment settings in one group

Say three pieces of code call your payment provider: a platform function that creates checkouts, a component function that records refunds, and a workflow that sends receipts. You create a `payments` group in the global environment with the provider's base URL and an encrypted API key, and read it where needed:

![Adding PAYMENT_API_KEY to the payments group, marking it Secret, saving, and seeing it listed as Encrypted](https://blog.protokol.io/content/images/2026/11/02-add-encrypted-key.gif)  
*Add the key, mark it Secret and save: the value is stored encrypted and never shown again.*

```js
const payments = $globalEnv.group("payments")
const baseUrl = payments.PAYMENT_API_URL
const apiKey = payments.PAYMENT_API_KEY   // left out unless the run identity may read it

```

When the provider changes its URL, you edit one value. Only identities that hold `secrets::read global_env.payments` receive the key, and code that doesn't hold that permission still runs with the plain values.

## Learn more

- [Security model](https://docs.protokol.io/platform/security-model/?ref=blog.protokol.io)
- [Run identity](https://docs.protokol.io/platform/run-identity/?ref=blog.protokol.io)
- [Platform functions: environment and global env](https://docs.protokol.io/platform/functions/?ref=blog.protokol.io)
- [Workflow expression context: $globalEnv](https://docs.protokol.io/workflow/expression-context/?ref=blog.protokol.io)
- [Component functions](https://docs.protokol.io/components/functions/?ref=blog.protokol.io)