Workflow Secrets API

A workflow secret is a named credential, such as a provider API token, stored for one workflow. Steps refer to it as {{secrets.KEY}}, so the value never appears in the workflow definition. Values are encrypted before they are stored and are never returned by the API.

The workflow must belong to your company, otherwise every endpoint returns 404.

Secret object

key is UPPER_SNAKE_CASE: it starts with a letter, uses only A-Z, 0-9 and _, and has at most 64 characters. A value is 1 to 8,192 characters.

List secrets

GET /api/v1/workflows/{workflowId}/secrets

Returns the workflow's secrets in data, sorted by key. No values are included.

Create a secret

POST /api/v1/workflows/{workflowId}/secrets

curl -X POST 'https://workflow.loopfour.ai/api/v1/workflows/c3a1f7d2-58e4-4b9a-8f21-6d0e9b7c4a15/secrets' \
  -H 'x-api-key: wfk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "BANK_PORTAL_TOKEN", "value": "your_token_value_here" }'

{
  "success": true,
  "data": {
    "id": "a3d5f8e2-1c7b-4e9a-8b40-2f6d1c9e7a53",
    "workflowId": "c3a1f7d2-58e4-4b9a-8f21-6d0e9b7c4a15",
    "key": "BANK_PORTAL_TOKEN",
    "maskedValue": "••••here",
    "lastUsedAt": null,
    "createdAt": "2026-02-12T09:00:00.000Z",
    "updatedAt": "2026-02-12T09:00:00.000Z"
  }
}

The response is 200. A key that already exists for the workflow returns 409 (Secret key already exists for this workflow).

Update a secret

PUT /api/v1/workflows/{workflowId}/secrets/{key}

Takes value and replaces the stored value. The next run uses the new value. An unknown key returns 404.

Delete a secret

DELETE /api/v1/workflows/{workflowId}/secrets/{key}

Returns { "deleted": true }. A run of a workflow whose steps still refer to the key fails with Missing required secrets: KEY.

Use a secret in a step

Refer to the key in any step setting, for example an API Request header:

{
  "id": "fetch_balances",
  "type": "action",
  "name": "Fetch bank balances",
  "action": "api.request",
  "config": {
    "url": "https://bank.example.com/v1/balances",
    "method": "GET",
    "headers": { "Authorization": "Bearer {{secrets.BANK_PORTAL_TOKEN}}" }
  }
}

The value is filled in when the step runs. See Variable references for the other references.

Errors