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

# Secrets on Protokol: global env and component secrets
- URL: https://blog.protokol.io/secrets/
- Published: 2026-11-17T17:33:13.000Z
- Updated: 2026-11-17T17:33:13.000Z
- Description: How Protokol keeps API keys and passwords safe: write-only secrets in global env and components, read only by the code identities you allow.
- Author: Strahinja Djuric
- Tags: Security, Engineering

Almost every integration needs something you don't want lying around: a payment provider's API key, an SMTP password, a webhook signing key. Your code needs the value at run time. Nobody else should ever see it again.

Protokol gives you two places to keep them:

- **Global env**: project-wide values in `$globalEnv`, available to your functions and workflows.
- **Component secrets**: values that belong to one component, available to that component's functions as `$secrets`.

Both follow the same model. This post walks through it.

## Five promises

Wherever a secret lives, the platform guarantees the same five things:

1. **Encrypted at rest.** Every stored secret value is encrypted.
2. **Write-only.** Once saved, a secret is never shown again. No API response, dashboard page, log or audit record returns it.
3. **Changing a secret needs an explicit permission.** Being able to edit a function or a component isn't enough.
4. **Code gets secrets only by permission.** A run receives encrypted values only when the identity it runs as is allowed to read them.
5. **Audited by name, never by value.** Every change is recorded with who did it and which key, never what the value was.

## Writing a secret

Secrets are written with a small set of prefixes. They work the same in a function's env and in global env:

| You write             | Meaning                                                    | Reads back as |
| --------------------- | ---------------------------------------------------------- | ------------- |
| secret::<value>       | Store this value as a secret                               | secretref::   |
| secretgen::random(64) | Let the platform generate a value                          | secretref::   |
| secretref::           | Keep the secret already stored here                        | secretref::   |
| literal::<value>      | A plain value that happens to start with a reserved prefix | the value     |

```json
{
  "env_variables": {
    "live": {
      "STRIPE_SECRET_KEY": "secret::sk_live_…",
      "SESSION_KEY": "secretgen::random(64)",
      "WEBHOOK_URL": "https://example.com/hook"
    }
  }
}

```

Read the function back and both secrets come back as `secretref::`, while `WEBHOOK_URL` comes back as it is. Your code receives the real values in `$env`.

`secretref::` is what makes write-only practical. Because every read returns it, you can load a configuration, change one plain value and save it back. The secrets you didn't touch are kept, and nobody had to see them.

A few guard rails apply:

- A supplied secret must be at least 8 characters. Shorter values are refused, because they can't be reliably scrubbed from output (more on that below).
- A generated secret must carry at least 128 bits of entropy. `secretgen::random(8, digits)` is refused.
- An identifier is not a secret, so `uuid` is not a generator.

To replace a secret, set it again. There is no "reveal" button, and there is no route that returns a stored value.

## Global env

Global env is your project's shared configuration, available as `$globalEnv` wherever your code runs. Plain values reach every run. **Encrypted values reach a run only when the code's run identity holds `secrets::read global_env`.** Without it, the run gets the plain values and the encrypted keys are simply absent.

That ties secrets to [run identities](https://docs.protokol.io/platform/run-identity/?ref=blog.protokol.io): you decide which identity your code runs as, and that identity decides which secrets the code sees.

### Groups

Most projects shouldn't hand every secret to every piece of code. Global env can be split into **groups**, each with its own read and write permissions:

| Permission                          | Covers                                        |
| ----------------------------------- | --------------------------------------------- |
| secrets::read global\_env.payments  | Reading the payments group's encrypted values |
| secrets::write global\_env.payments | Changing them                                 |
| secrets::read global\_env           | Reading every group                           |

Put your payment provider's keys in a `payments` group, give only the "Order processing" role `secrets::read global_env.payments`, and run your checkout code as that role. Your newsletter code, running as another role, never receives those keys.

A run sees every key it may read at the top level of `$globalEnv`. To read one group explicitly:

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

```

Key names are unique across groups, so groups never overwrite each other.

## Component secrets

Some secrets belong to one component and nowhere else, such as the signing key for its sessions or the SMTP password its notification function uses. These are **component secrets**. You declare them in the component's settings, next to `config`:

```json
{
  "secrets": {
    "session_key": "secretgen::random(64)",
    "smtp_password": "secret::"
  }
}

```

There are two kinds:

- **Generated** (`secretgen::…`). The platform creates the value. Your app never needs to know it, and you can rotate it with one call.
- **Supplied** (`secret::`). You provide the value, through the dashboard, the API or a Forge install script.

Values are **per environment**: dev and live each have their own, so a test key never ends up in production.

The component's functions read them from `$secrets`:

```js
if (!$secrets.smtp_password) {
  throw new Error("smtp_password is not set for " + $currentEnv)
}

```

A supplied secret that hasn't been set yet is `undefined`, so check for it in code that needs it.

### Seeing what's set, without seeing values

The status endpoint tells you, per environment, whether each secret has a value and whether it was generated or supplied. It never tells you what the value is:

```json
{
  "name": "smtp_password",
  "declaration": "secretref::",
  "envs": {
    "dev":  { "status": "set", "origin": "supplied", "updated_at": "2026-10-27T09:15:02Z" },
    "live": { "status": "missing" }
  }
}

```

### Templates and copies carry declarations only

Copying a component into another project, or installing it from a template, carries the declarations but never the values. Generated secrets are created fresh in the new project. Supplied secrets start as missing. A template that tries to carry a value is refused when it's published.

## Who can do what

Changing a secret and using one are separate permissions:

| To                                                    | You need                                                                                              |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Set, generate, rotate or remove a component secret    | secrets::write <ref>                                                                                  |
| Set or replace a secret in a function's env           | manage base\_functions and secrets::write base\_functions                                             |
| Set or replace a global env secret                    | manage global\_env and secrets::write global\_env (or secrets::write global\_env.<group> for a group) |
| Change plain values, or keep secrets with secretref:: | The resource's usual permission only                                                                  |

The Owner and Maintainers hold these by default. Anyone else needs them added to a role.

There's one more rule, and it's the honest one: **whoever can change code can read every secret that code receives.** If you can edit a function that receives the SMTP password, you can make it send that password anywhere. No platform can prevent that, so Protokol makes it explicit. Changing code that receives secrets needs the matching read permission, `secrets::read <ref>` for a component that declares secrets and `secrets::read base_functions` for a function with encrypted env, plus the code's run identity. These permissions never return a value. They decide who may change code that has secrets.

Without that permission, the code and the secret declarations are read-only in the dashboard, which names the missing permission. Settings that aren't code stay editable.

## Keeping secrets out of output

Secrets most often leak by accident: a stack trace, a debug log, an error message that echoes a request. Protokol **scrubs every value a run received** from the error output and captured logs returned to the caller. It catches the value as is and in common encodings such as JSON, URL, base64 and HTML.

Scrubbing is a safety net, not a guarantee. It can't catch code that changes a value on purpose, for example by logging half of it, hashing it or reversing it. That's also why secrets under 8 characters are refused: short values can't be scrubbed safely.

A few more boundaries:

- Model events and workflow expressions don't receive component secrets.
- A function run that sends its own code instead of the saved code receives no secrets at all.
- A run that overrides a component's `config` needs the component's settings permission when secrets are involved, because a changed config could send them somewhere else.

## Your part

The platform keeps values encrypted, write-only and out of output. Some decisions stay with your team:

- **Deploy rights are secret access.** Anyone who can change or deploy code can read the secrets that code receives. Grant Owner, Maintainer and deploy rights accordingly.
- **Narrow identities and groups.** Give each piece of code the identity it needs, and only that identity the global env groups it needs.
- **Rotate** when someone leaves or you suspect a leak. A generated component secret rotates with one call. Supplied secrets you set again.
- **Don't log secrets**, even partially.

The full reference, with every route and error, is in the documentation: [Component secrets](https://docs.protokol.io/components/secrets/?ref=blog.protokol.io), [Function and global env](https://docs.protokol.io/platform/functions/?ref=blog.protokol.io#environment-variables) and the [Security model](https://docs.protokol.io/platform/security-model/?ref=blog.protokol.io).