Secrets on Protokol: global env and component secrets

How Protokol keeps API keys and passwords safe: write-only secrets in global env and components, read only by the code identities you allow.

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
{
  "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: 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:

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:

{
  "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:

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:

{
  "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, Function and global env and the Security model.