> ## 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.

# Secrets

> Store credentials safely and mount them into workflow blocks

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:

```text theme={null}
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.

<Warning>
  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.
</Warning>

## Create And Manage Secrets

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

```bash theme={null}
retab secrets set RESEND_API_KEY --from-stdin
```

or:

```bash theme={null}
retab secrets set RESEND_API_KEY --from-file ./resend-api-key.txt
```

List and inspect metadata:

```bash theme={null}
retab secrets list
retab secrets get RESEND_API_KEY
```

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

```bash theme={null}
retab secrets value RESEND_API_KEY
```

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

```bash theme={null}
export RESEND_API_KEY="$(retab secrets value RESEND_API_KEY)"
```

For structured tooling, request JSON:

```bash theme={null}
retab secrets value RESEND_API_KEY --output json
```

Delete a secret:

```bash theme={null}
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.

```json theme={null}
{
  "mounts": {
    "secrets": [
      {
        "name": "RESEND_API_KEY"
      }
    ]
  }
}
```

## Function Blocks

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

```python theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
retab workflows blocks pull-config wf_123 blk_api --out tmp/api
```

The local bundle includes:

```text theme={null}
.env.example
.env.local
```

By default, `.env.local` contains placeholders:

```bash theme={null}
PARTNER_API_TOKEN=__REPLACE_ME__
```

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

```bash theme={null}
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:

```bash theme={null}
retab workflows blocks api-calls hydrate tmp/api --fill-secrets --force-secrets
```

Local runtime resolution order is:

```text theme={null}
shell environment > .env.local
```

That lets you override one run without editing the file:

```bash theme={null}
PARTNER_API_TOKEN=override retab workflows blocks api-calls run tmp/api samples/order.json --execute
```

## API Reference

* [List Secrets](/api-reference/secrets/list)
* [Create Secret](/api-reference/secrets/create)
* [Get Secret Metadata](/api-reference/secrets/get)
* [Get Secret Value](/api-reference/secrets/value)
* [Set Secret](/api-reference/secrets/set)
* [Delete Secret](/api-reference/secrets/delete)

## 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.