Secrets Module

Securely store and retrieve sensitive values at runtime

The secrets module lets automations securely store and retrieve sensitive values (API keys, tokens, credentials) at runtime. Values are encrypted at rest and never exposed as plaintext in automation outputs or logs.

This page documents two things:

• The runtime API (secrets.set, secrets.get, secrets.delete) for automations.
• The Settings → Secrets form in the Builder UI, which is where workspace-level secrets are typically configured before any automation runs.

Settings → Secrets form

Open Settings → Secrets in the Builder. The form has two sections.

Schema-defined secrets

The top section is generated from the workspace’s secret schema, declared in index.yml:

secrets:
  schema:
    openaiApiKey:
      type: string
      description: API key for the OpenAI integration
    notionToken:
      type: string
      description: Notion integration token

Every property of the schema is rendered as an input field. These are the “main” secrets of the workspace: they have known names, automations reference them as {{secret.<name>}}, and someone (usually the workspace author) committed the schema to source control.

Typing a value and clicking Save Secrets posts the new values to POST /workspaces/{id}/secrets. Values are stored encrypted; the form never reads back plaintext (an empty field means “leave the existing value untouched”, not “clear the value”).

Additional Secrets form

The “Additional Secrets” section underneath is for secrets that are not declared in the schema. The label “Additional” is intentional: these are extras beyond the schema-defined set.

Field	Notes
New key	The variable name. Will be readable from automations as {{secret.<key>}}.
New value	Hidden by default (password input). The eye icon toggles visibility.
+ button	Adds the pair to the in-memory list. The secret is not persisted until you press Save Secrets.
Delete (per row)	Removes the row from the in-memory list.
Save Secrets	Persists the schema values and the additional secrets in one call.

Use the Additional form when:

• You are prototyping and have not yet committed a schema.
• You need an environment-specific override (e.g. a per-deploy webhook URL) that should not appear in source.
• You want a one-off value usable from a single automation without touching index.yml.

Once a name stabilizes, promote it to the schema so the next workspace clone has the documentation built in.

The “Additional Secrets” form persists plaintext values to the workspace’s encrypted secret store. It is not a temporary scratchpad; entries survive reloads and pulls (unless overwritten by a pulled index.yml).

Runtime API

For automations that need to create or rotate secrets at runtime (OAuth tokens, refresh tokens, per-user credentials), the secrets module exposes set, get, and delete.

How it works

1. secrets.set and secrets.get return an opaque secret reference (a $secret:... string), not the actual value.
2. When this reference is used inside a fetch instruction (in the URL, headers, body, query, or auth fields), the platform automatically resolves it to the real value just before the HTTP call.
3. The resolved value is redacted from all logs and events.

Secret references are short-lived (a few minutes). Always call secrets.get right before using the reference; do not store it for later reuse.

Scopes

Scope	Description
workspace	Belongs to the workspace, not to whoever triggers the automation. Readable by workspace editors, or by any per-name access rule (secure_secrets) that matches the caller.
user	Belongs to one user. Only ever reachable by a run that carries that user’s context. There is no way to read a user secret from a run without a user — see below.

Access model — who can read a secret

Whether secrets.get (and set/delete) succeeds depends on three independent things:

1. The scope requested — user or workspace.
2. Whether the run carries an authenticated user — i.e. ctx.source.userId is set. Interactive runs (a user clicking in the UI, an API call with a user token, a page render) carry a user. Cron/schedule triggers, anonymous webhooks, emit-triggered runs, and in-process cross-workspace calls do not.
3. Whether the call took on one of the workspace’s own roles — assumeRole on the run instruction, which only ever helps a workspace secret (see Reading a workspace secret with no user).

Access matrix

Scope	Run	Result
user	Authenticated (user present)	✅ Reads that user’s own secret.
user	No user (cron, schedule, anonymous webhook, cross-workspace call)	❌ Returns { error: "user_required" }. No role changes this — the module refuses scope: user without a user before permissions are ever consulted, so a user secret is unreachable without its user.
workspace	Authenticated, with the right role or a matching secure_secrets rule	✅ Normal RBAC read.
workspace	No user, no assumeRole (a plain cron, an anonymous webhook, a call from another workspace)	❌ Returns { error: "not_found" }. The secret exists but is invisible — a user-less run holds no role.
workspace	assumeRole: <role>, that role carrying a read rule on secure_secrets whose name covers the secret	✅ Read under the workspace’s own rule.
workspace	assumeRole: <role>, but the role is undeclared or its rule does not cover the name	❌ { error: "not_found" }, with a message naming what to declare.

set and delete follow the same path as get, under the same assumed role: a run that can read a rotating token can also store its replacement, and drop one the provider has rejected for good. Reading without writing would be a half-feature — the run would burn the token and fail on the next pass — and without deleting, a dead token is retried forever.

Reading a workspace secret with no user

A workspace secret is invisible to a run that carries no user: reads resolve RBAC against the caller, and a user-less trigger holds no role, so it sees nothing. That is exactly the situation of a scheduled synchronisation — the credentials the workspace’s own members deposited are unreadable to the workspace’s own sync.

Nothing about the shape of the run answers it. An unauthenticated cron and an unauthenticated HTTP call are indistinguishable, and a sync typically reaches the connector by endpoint rather than by schedule. So the workspace states the entitlement itself: it declares a role in its security.yml, and the automation takes that role on for the one call that needs it.

1. Members deposit their own credential

A connector lets its members write their own token — a secure_secrets rule in the workspace’s security.yml, carried by no role, so it applies to every member. Example (Figma connector):

# security.yml
authorizations:
  rules:
    - action:
        - create
        - update
      subject: secure_secrets
      conditions:
        name:
          $regex: '^figRefresh_${user.id}$'
      reason: |
        A member connecting their own account deposits the refresh token that a
        scheduled sync will later replay.

The platform validates this rule strictly and forces two conditions you do not write — workspaceId (the current workspace) and scope: workspace. The rule must obey:

Requirement	Why
subject: secure_secrets	Targets the encrypted runtime store (secrets.set / get).
action: only create / update / read	manage is refused outright, and delete is grantable only to a role (below), never on a rule applying to every member. read is accepted here, but only ever makes sense on a role-carried rule: granting it to everyone would let each member read all the others’ credentials.
name confines to the acting user	Otherwise one rule would let any member overwrite another’s credential. Use {$regex: '^<head>${user.id}<suffix>$'} — anchored at both ends, ${user.id} present exactly once, only literal characters around it, plus at most one fixed-width character class (e.g. [a-f0-9]{16}) for connectors holding several credentials per person.
not inverted	An inverted: true rule is a DENY, and a deny grants nothing.

A connector holding several credentials per remote account carries a discriminator with the fixed-width class (SharePoint):

    - action: [create, update]
      subject: secure_secrets
      conditions:
        name:
          $regex: '^spnRefresh_[a-f0-9]{16}_${user.id}$'

The width must be fixed ({16}, never + / * / {n,m}) and the class must sit before ${user.id}: a variable-width segment next to the id would let two different (account, user) pairs spell the same name.

2. A role reads — and writes back — the whole family

The run that replays those tokens has no user to bind to, so its rule names a family of secrets instead, and it is carried by a role the workspace declares:

# security.yml
authorizations:
  roles:
    tokenResolver: {}
  rules:
    - role: tokenResolver
      action:
        - read
        - create
        - update
        - delete
      subject: secure_secrets
      conditions:
        name:
          $regex: '^figRefresh_'
      reason: |
        The scheduled sync replays any connected member's token, stores the
        rotated one the provider hands back, and drops one rejected for good.

What a rule must prove depends on who it applies to, not on the action:

• a rule carrying no role: lands on default, which applies to every member, so ${user.id} stays mandatory — it is the only thing keeping members apart;
• a rule carried by a role applies to whoever takes it on, which is an automation acting for the workspace. It may name a family, for reads (a sync serves everyone) and for writes alike (a provider rotating its refresh tokens hands back a new one that must be stored for a member who is not there). A role-carried rule may also pin ${user.id} — strictly narrower, and accepted on its own terms.

A family pattern is checked as strictly as the user-bound one:

Requirement	Example
anchored at the start with ^	^figRefresh_
no ${user.id} — it binds to nobody in a run with no user	^spnRefresh_
every character literal, apart from at most one fixed-width class	^spnRefresh_[a-f0-9]{16}_
a literal head of at least 6 characters, ending on _, -, : or /	figRe_ ✅, fig_ ❌
never the reserved prismeai_ namespace	^prismeai_ ❌

The head is what a caller cannot vary, and it is what names the family — ending it on a separator is what stops onnRefresh_ from also matching onnRefreshOther. The resulting pattern deliberately matches every member’s figRefresh_<id>: that breadth is the point, a scheduled sync must be able to reach any connected user’s token.

3. The automation takes the role on

- run:
    function: secret.get
    assumeRole: tokenResolver
    parameters:
      name: 'figRefresh_{{targetUserId}}'
      scope: workspace

assumeRole applies to that single call. Everything around it keeps the caller’s own rights, and nothing is carried to the automations it calls, to an emit, or across a workspace boundary. It replaces the caller’s rights rather than adding to them, so the role has to be sufficient on its own for what the call does.

Only a role the workspace declared can be assumed: owner is refused, so a developer has to state what they are opening. And whatever the role, scope: user stays out of reach — the module refuses it without a user before RBAC is consulted.

Anything holding that role can read and overwrite every credential in the family. That is the price of servicing absent users, and it is why the role should exist for that purpose alone: do not assign it to a person, and do not give it an auth block. An API key bound to it would hand every member’s credential to whoever holds the key. The platform does not prevent either — it is yours to decide.

Per-user connector tokens (OAuth refresh tokens, etc.) are not stored as user secrets. They are workspace secrets whose name embeds the user id (figRefresh_<id>), deposited under the rule above. That is why a role — which only ever reaches workspace secrets — is what lets a scheduled sync replay a given user’s token.

See RBAC → secure secrets for the security rules, and Automations → assumeRole for the instruction.

Functions

set: Store or update a secret

- run:
    module: secrets
    function: set
    parameters:
      name: myApiKey
      value: "sk-live-abc123"
      scope: workspace
    output: secretRef

Parameter	Type	Required	Description
name	string	yes	Unique name for the secret (within its scope)
value	any	yes	The value to encrypt and store
scope	user | workspace	yes	Storage scope
ttl	number	no	Time-to-live in seconds. The secret expires and becomes unreadable after this duration.

Returns a $secret:... reference string. If a secret with the same name and scope already exists, it is updated.

get: Retrieve a secret reference

- run:
    module: secrets
    function: get
    parameters:
      name: myApiKey
      scope: workspace
    output: secretRef

Parameter	Type	Required	Description
name	string	yes	Name of the secret to retrieve
scope	user | workspace	yes	Storage scope

Returns a $secret:... reference string, or { error: "not_found" } if the secret does not exist (or has expired).

delete: Remove a secret

- run:
    module: secrets
    function: delete
    parameters:
      name: myApiKey
      scope: workspace
    output: result

Parameter	Type	Required	Description
name	string	yes	Name of the secret to delete
scope	user | workspace	yes	Storage scope

Returns { deleted: true } on success, or { error: "not_found" }.

Using secret references in fetch

Pass the reference returned by set or get wherever a sensitive value is needed in a fetch instruction. The platform resolves it transparently:

do:
  # 1. Retrieve the secret reference
  - run:
      module: secrets
      function: get
      parameters:
        name: myApiKey
        scope: workspace
      output: secretRef

  # 2. Use it in a fetch: the platform injects the real value at execution time
  - fetch:
      url: https://api.example.com/data
      method: GET
      headers:
        Authorization: "Bearer {{secretRef}}"
      output: apiResponse

Resolution is supported in these fetch fields: url, headers, body, query, and auth (including auth.awsv4).

Secret references expire after a few minutes. Always retrieve the reference (secrets.get) in the same automation run where you use it.

Complete example: storing and using an OAuth token

slug: call-with-oauth
name: Call API with OAuth token
do:
  # Authenticate and get a token
  - fetch:
      url: https://auth.example.com/oauth/token
      method: POST
      body:
        grant_type: client_credentials
        client_id: "{{config.clientId}}"
        client_secret: "{{secret.clientSecret}}"
      output: authResponse

  # Store the token as a workspace secret with a 1-hour TTL
  - run:
      module: secrets
      function: set
      parameters:
        name: oauthToken
        value: "{{authResponse.access_token}}"
        scope: workspace
        ttl: 3600
      output: tokenRef

  # Use the token in subsequent API calls
  - fetch:
      url: https://api.example.com/resources
      method: GET
      headers:
        Authorization: "Bearer {{tokenRef}}"
      output: resources

Error handling

All three functions return an error object instead of throwing when the error is actionable:

Error	Returned by	Meaning
{ error: "not_found" }	get, delete	No secret with that name/scope exists (or it has expired), or it exists but the run cannot reach it — a user-less run on a workspace secret that assumed no role, or a role whose rule does not cover that name. In that case the accompanying message says so, names what to declare (a read rule on secure_secrets carried by a role, and the assumeRole that takes it on) and states this is not an expired user token.
{ error: "user_required" }	set, get, delete	scope: user was used but there is no user context (e.g. cron trigger). No role can substitute for the missing user: the module refuses before permissions are consulted.

Use onError or a conditions block to handle these:

- run:
    module: secrets
    function: get
    parameters:
      name: myApiKey
      scope: workspace
    onError: continue
    output: result
- conditions:
    '{{result.error}}':
      - emit:
          event: secret-missing
          payload:
            message: "Secret myApiKey not found"