Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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 environment variable name that should be available to the runtime. 
{
  "mounts": {
    "secrets": [
      {
        "name": "RESEND_API_KEY",
        "env": "RESEND_API_KEY",
        "required": true
      }
    ]
  }
}
If env is omitted, Retab uses the secret name as the environment variable name.

​
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

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