Secrets

Workflow secrets are environment-scoped credentials that Retab can inject into workflow execution without storing raw values in block code or workflow config. Use secrets for API keys, bearer tokens, basic auth passwords, partner credentials, and other values that should not appear in prompts, block configs, or run output.

How Secrets Work

A secret has a stable name and an encrypted value:

RESEND_API_KEY
LOREAL_API_TOKEN
XPO_BASIC_AUTH

The name is visible in metadata, workflow config, logs, and local bundles. The value is encrypted at rest and is only resolved when a workflow runtime needs it or when an authorized user explicitly asks for the value.

Do not paste secret values into function code, API-call headers, prompts, block labels, test fixtures, or sample JSON files. Store the value as a Retab secret and reference it by name.

Create And Manage Secrets

Use the CLI to create and update secrets without putting values in shell history:

retab secrets set RESEND_API_KEY --from-stdin

or:

retab secrets set RESEND_API_KEY --from-file ./resend-api-key.txt

List and inspect metadata:

retab secrets list
retab secrets get RESEND_API_KEY

Metadata responses do not include the secret value. To read a value explicitly:

retab secrets value RESEND_API_KEY

This prints the raw value so it can be used in shell commands:

export RESEND_API_KEY="$(retab secrets value RESEND_API_KEY)"

For structured tooling, request JSON:

retab secrets value RESEND_API_KEY --output json

Delete a secret:

retab secrets delete RESEND_API_KEY

Mount Secrets Into Blocks

Blocks declare the secrets they need through mounts.secrets. A mount maps the Retab secret name to the same environment variable name inside the runtime.

{
  "mounts": {
    "secrets": [
      {
        "name": "RESEND_API_KEY"
      }
    ]
  }
}

Function Blocks

Function blocks receive mounted secrets as environment variables. Read them with os.environ:

import os
from models import Input, Output

def transform(input_data: Input) -> Output:
    api_key = os.environ["RESEND_API_KEY"]
    return Output(has_api_key=bool(api_key))

Keep the value out of returned output and traces. If a function needs to call an external HTTP API, prefer an API-call block because function sandboxes do not have outbound network access.

API-Call Blocks

API-call blocks can reference mounted env vars in URL, header, and body fields:

{
  "method": "POST",
  "url": "https://api.example.com/orders",
  "headers": {
    "Authorization": "Bearer ${PARTNER_API_TOKEN}",
    "Content-Type": "application/json"
  },
  "mounts": {
    "secrets": [
      {
        "name": "PARTNER_API_TOKEN",
        "env": "PARTNER_API_TOKEN"
      }
    ]
  }
}

Rendered request artifacts redact sensitive headers. The raw value is still used for execution.

Local Development

When you pull a function or API-call block config locally, Retab generates placeholder env files:

retab workflows blocks pull-config wf_123 blk_api --out tmp/api

The local bundle includes:

.env.example
.env.local

By default, .env.local contains placeholders:

PARTNER_API_TOKEN=__REPLACE_ME__

You can fill the values yourself, export them in your shell, or let Retab fill them explicitly:

retab workflows blocks api-calls hydrate tmp/api --fill-secrets
retab workflows blocks functions hydrate tmp/fn --fill-secrets

--fill-secrets writes values only to .env.local, never to config.json or manifest.json, and it does not print secret values. Existing local values are preserved by default. To overwrite them:

retab workflows blocks api-calls hydrate tmp/api --fill-secrets --force-secrets

Local runtime resolution order is:

shell environment > .env.local

That lets you override one run without editing the file:

PARTNER_API_TOKEN=override retab workflows blocks api-calls run tmp/api samples/order.json --execute

API Reference

Best Practices

Use one secret per credential and name it after the environment variable the runtime should receive.
Keep test and production credentials in separate Retab environments.
Reference secrets through mounts.secrets; do not inline raw values in block config.
Treat retab secrets value and --fill-secrets as explicit local developer actions.
Do not commit .env.local, sample files containing credentials, or rendered unredacted request artifacts.

Overview

Primitives

Workflows

Core Concepts

Enterprise

How Secrets Work

Create And Manage Secrets

Mount Secrets Into Blocks

Function Blocks

API-Call Blocks

Local Development

API Reference

Best Practices

​How Secrets Work

​Create And Manage Secrets

​Mount Secrets Into Blocks

​Function Blocks

​API-Call Blocks

​Local Development

​API Reference

​Best Practices

How Secrets Work

Create And Manage Secrets

Mount Secrets Into Blocks

Function Blocks

API-Call Blocks

Local Development

API Reference

Best Practices