> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Call any API from a workflow without exposing the key

> Call an API that needs a key from a Reliant workflow while no step, model or log ever holds the value: store it, declare it, allow the workflow, and run it.

By the end of this guide a workflow calls an API with a bearer key, and the key is in no step input, run state, log, message or model context. The worker fetches the value for one step attempt and writes it only into the outgoing request header. [HTTP: secrets](https://docs.reliantlabs.io/integrations/http.md#secrets) is the full rule set; this guide walks through one call.

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)), as an organization owner or admin: only they can store a secret or allow a workflow to use it.
* A forge project with a hosted environment to hold the secret. This guide uses `staging` of a project named `guides-sandbox-webhook` ([Secrets](https://docs.reliantlabs.io/hosting/secrets.md)).
* A Reliant project for the repository the workflow lives in, and its ID (`reliant project list`).

**1. Store the key**

Run this in the forge project. `secret set` reads the value from stdin, so it stays out of your shell history:

```bash terminal theme={null}
reliant forge env secret set --env staging DEMO_API_KEY < key.txt
```

```text theme={null}
DEMO_API_KEY: created v1 (36 bytes) in hosted env "staging" at https://admin.reliantapi.com
```

Nothing reads a hosted value back, this command included. `reliant forge env secret list --env staging` calls the key "inert", because no workload declares it. A workflow-only secret is meant to look like that.

**2. Declare the secret and put it in a header**

`secrets:` names the environment as `<forge project>/<env>`. The reference `{{ secrets.DEMO_API_KEY }}` is allowed only in a credential slot: an `http/request@1` header, or `credential: { secret: NAME }` on an integration action.

```yaml .reliant/workflows/check-api-key.yaml theme={null}
name: check-api-key
description: Call an API that needs a bearer key, with the key held by Reliant and never shown to a step or a model.

secrets:
  DEMO_API_KEY:
    environment: guides-sandbox-webhook/staging

entry: [call]

nodes:
  - id: call
    type: action
    uses: http/request@1
    with:
      url: https://httpbin.org/bearer
      method: GET
      timeout: 15
      headers:
        Authorization: "Bearer {{ secrets.DEMO_API_KEY }}"

  - id: report
    type: save_message
    args:
      role: assistant
      content: "The API answered {{ nodes.call.data.status }}; authenticated: {{ nodes.call.data.json.?authenticated.orValue(false) }}"

  - id: failed
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: "The call failed: {{ nodes.call.content }}"

edges:
  - from: call
    cases:
      - to: failed
        condition: nodes.call.is_error
    default: report
```

Keep the URL a literal you trust. The key goes to whatever host the request starts at, so never build that origin from an input, a webhook payload or model output. The response is under `nodes.call.data` (`status`, `headers`, `json`, `text`). `nodes.call.is_error` is true when the call failed.

**3. Check it locally**

```bash terminal theme={null}
reliant workflow validate .reliant/workflows/check-api-key.yaml
reliant workflow lint .reliant/workflows/check-api-key.yaml
```

Both pass. Lint warns `[scenario-none]` until you add [scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md); a scenario mocks the `call` step, so no secret is fetched. A secret anywhere but a credential slot fails validation:

```text theme={null}
Error: check-api-key.nodes.call.with.url: secrets.NAME may not be used here: a secret travels only in a credential slot, never in text a step or a model can read, print or return
```

**4. Allow the workflow to use it**

A secret's access list names the workflows that may use it, by Reliant project and workflow name:

```bash terminal theme={null}
reliant forge env secret allow --env staging --workflow check-api-key \
  --project 4c42479e-ef9d-44c3-a4d8-a37a6465d1fb DEMO_API_KEY
reliant forge env secret access --env staging DEMO_API_KEY
```

```text theme={null}
allowed workflow "check-api-key" (Reliant project 4c42479e-ef9d-44c3-a4d8-a37a6465d1fb) to use DEMO_API_KEY in hosted env "staging" at https://admin.reliantapi.com
access to DEMO_API_KEY in hosted env "staging" at https://admin.reliantapi.com

  workflow "check-api-key" (project 4c42479e-ef9d-44c3-a4d8-a37a6465d1fb) granted by d84faf93-… at 2026-11-20T10:36:20.782589Z
```

When someone enables an automation of this workflow, its approval card lists the secret too.

**5. Run it and verify**

Commit the workflow, then run it:

```bash terminal theme={null}
reliant workflow run check-api-key --project-id 4c42479e-ef9d-44c3-a4d8-a37a6465d1fb --follow
```

The run ends at `report` with `The API answered 200; authenticated: true`. httpbin's `/bearer` echoes the token it received, which makes it a good test of what the run kept. The `call` step's recorded input and output:

```json call step (recorded) theme={null}
{"with": {"headers": {"Authorization": "Bearer ⟦ secret:DEMO_API_KEY⟧"}, "url": "https://httpbin.org/bearer"}}
{"data": {"status": 200, "json": {"authenticated": true, "token": "[secret]"}}}
```

The input holds a placeholder, never the value. The worker replaced the echoed value with `[secret]` before anything recorded it. An agent step that reads `nodes.call.data` sees only that.

**6. Revoke and clean up**

```bash terminal theme={null}
reliant forge env secret deny --env staging --workflow check-api-key \
  --project 4c42479e-ef9d-44c3-a4d8-a37a6465d1fb DEMO_API_KEY
reliant forge env secret unset --env staging DEMO_API_KEY
```

`deny` takes effect on the next step that asks for the value: the next run of `check-api-key` failed with the access-list refusal below. `unset` soft-deletes the value and keeps its version history.

## What this does not do

* **It does not make the API you call trustworthy.** The remote server receives the key. Only an exact echo is replaced with `[secret]`; an API that returns the key encoded or reworded returns it readable. Send a secret only to the API it belongs to.
* **Agents and commands never get the value.** A `run` step can't take a secret at all, and text that reaches a step as data, such as a prompt, a model's output or an input, is never treated as a secret reference, even if it contains `{{ secrets.NAME }}`.
* **The access list names a workflow, not a URL or a step.** Any step of an allowed workflow may put the secret in a header, so the workflow's URLs are the boundary. Review them like code.
* **Access lists are for hosted environments.** A local `FileSecrets` store has none.

## Troubleshooting

> [accordion] workflow "check-api-key" may not use secret DEMO\_API\_KEY in guides-sandbox-webhook/staging
>
> The workflow is not on the secret's access list. The message suggests `forge env secret allow DEMO_API_KEY --env staging --workflow check-api-key`. Add `--project <Reliant project id>`, which the command requires. The step reports the refusal as `is_error`, so the run above ended at `failed`.

> [accordion] CEL compilation error: undefined field 'status'
>
> An action's result is under `data`: write `nodes.call.data.status`, not `nodes.call.status`.

## Next steps

> [card] [Start an agent from a webhook](https://docs.reliantlabs.io/guides/workflows/start-agent-from-webhook.md)
>
> Start a run from an incoming request, then call out with the key.

> [card] [HTTP integration](https://docs.reliantlabs.io/integrations/http.md)
>
> Every `http/request@1` parameter, credential slots and transport rules.

> [card] [Reliant security model](https://docs.reliantlabs.io/deep-dives/security-model.md)
>
> How write-only hosted secrets and credential slots fit together.

> [card] [Secrets reference](https://docs.reliantlabs.io/hosting/secrets.md)
>
> Hosted secret stores, versions and protected environments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.