Secrets Module

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

secrets.set and secrets.get return an opaque secret reference (a $secret:... string), not the actual value.
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.
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`	Shared across all users in the workspace. Any workspace editor can read/update it.
`user`	Private to the current user. Only accessible by automations running in that user’s context. Not available in cron/schedule triggers (no user context).

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)
`{ error: "user_required" }`	`set`, `get`, `delete`	`scope: user` was used but there is no user context (e.g. cron trigger)

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"

Overview

Chat

Agent Creator

Knowledges

Collections

Builder

Governe

Engage

Insights

Settings → Secrets form

Schema-defined secrets

Additional Secrets form

Runtime API

How it works

Scopes

Functions

set: Store or update a secret

get: Retrieve a secret reference

delete: Remove a secret

Using secret references in fetch

Complete example: storing and using an OAuth token

Error handling

​Settings → Secrets form

​Schema-defined secrets

​Additional Secrets form

​Runtime API

​How it works

​Scopes

​Functions

​set: Store or update a secret

​get: Retrieve a secret reference

​delete: Remove a secret

​Using secret references in fetch

​Complete example: storing and using an OAuth token

​Error handling

Settings → Secrets form

Schema-defined secrets

Additional Secrets form

Runtime API

How it works

Scopes

Functions

set: Store or update a secret

get: Retrieve a secret reference

delete: Remove a secret

Using secret references in fetch

Complete example: storing and using an OAuth token

Error handling