> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Managing secrets

Secrets store sensitive values that external tools and HTTP-capable flow steps use in requests. You create a secret, reference it by name, and Runtype resolves its value at runtime. Runtype encrypts values at rest and scrubs them from model context, responses, streamed events, stored results, and logs.

## How secrets work

The secret value is write-only. After you save a secret, the dashboard and API return only metadata, including a masked preview. To change the value, rotate the secret. You can't retrieve the existing value.

The following table describes the properties of each secret:

| Property       | Description                                                                           | Values                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name           | The name that tool and flow configurations reference. Runtype stores it in uppercase. | 2 to 100 characters. Start with a letter, end with a letter or digit, and use only letters, digits, and underscores. For example, `STRIPE_API_KEY`. |
| Masked preview | A partial rendering that identifies the secret without revealing its value.           | Generated from the value.                                                                                                                           |
| Status         | Whether the secret resolves at runtime.                                               | `active`, `needs_configuration` (registered without a value), or `revoked`                                                                          |
| Version        | A counter that tracks value changes.                                                  | `1` for a secret created with a value, `0` for a secret without a value. It increments each time you set or rotate the value.                       |

You can't set the `revoked` status yourself from the dashboard, the CLI, the API, or the Runtype MCP server. A secret with the `revoked` status doesn't resolve, and the dashboard offers only **Delete** for it.

Runtype resolves secret values only where a tool or step supports them. It scrubs the values from streamed events, stored results, and logs.

## Add a secret

To add a secret in the dashboard, follow these steps:

1. Open **Settings > Secrets**.
2. Click **New secret**.
3. In the **Name** field, enter a name such as `STRIPE_API_KEY`.
4. In the **Value** field, paste the value. The value must be 8 to 10,000 characters.
5. Optional: In the **Description** field, describe what the secret is for.
6. Click **Save secret**.

Runtype encrypts the value, and the secret appears in the list with its masked preview.

### Add a secret with the CLI or API

To create a secret with the `runtype` CLI, pipe the value to the `runtype secrets create` command. The CLI reads the value from stdin, so the value doesn't appear in your shell history:

**`runtype CLI`**

```bash title="runtype CLI"
printf '%s' "$STRIPE_API_KEY" | runtype secrets create -k STRIPE_API_KEY
```

To create the same secret with the Runtype API, send a `POST` request to `/v1/secrets`:

**`cURL`**

```bash title="cURL"
curl https://api.runtype.com/v1/secrets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "STRIPE_API_KEY", "value": "YOUR_SECRET_VALUE"}'
```

Replace the following:

* `YOUR_API_KEY`: your Runtype API key
* `YOUR_SECRET_VALUE`: the value to store

An API key needs `SECRETS:READ` to list, get, and check secrets, and `SECRETS:WRITE` to create, update, and delete them. `SECRETS:*` grants both. For all endpoints and fields, see the [Secrets API reference](/api-reference/runtype-api/secrets/list-secrets-metadata-only).

### Scope a secret to a tenant or end user

By default, a secret belongs to your organization. To give each product tenant or end user its own value, create the secret with a `productTenantId` or `endUserId` field, or with the `--product-tenant-id` or `--end-user-id` CLI flag. A scoped secret must have a value.

A name can exist at only one level of an organization, tenant, and end-user chain. If the name already exists at another level of the same chain, Runtype returns `409`. For how an agent resolves scoped secrets, see [End-user identity and credentials](/developer-guides/guides/end-user-identity).

## Fill a pending secret

A secret without a value has the `needs_configuration` status. Templates and product setup can register these secrets, and you can register one yourself by creating a secret without a value through the API, the CLI, or the Runtype MCP server.

To set the first value in the dashboard, follow these steps:

1. Open **Settings > Secrets**. The row shows **needs value** and **No value set yet**.
2. On the row, click **Set value**.
3. In the **New value** field, paste the value.
4. Click **Rotate secret**. The secret becomes `active` at version `1`.

## Reference a secret in HTTP integrations

Use the `{{secret:NAME}}` syntax in supported request fields. Replace `NAME` with the name of your managed secret.

Use the following example to set HTTP header values:

**`HTTP header values`**

```plaintext title="HTTP header values"
Authorization: Bearer {{secret:STRIPE_API_KEY}}
X-API-Key: {{secret:SERVICE_KEY}}
```

Replace `STRIPE_API_KEY` and `SERVICE_KEY` with the names of your managed secrets.

At runtime, Runtype resolves each reference before it sends the request. The resolved value doesn't enter model context or the returned response.

References resolve in the following places:

* **External (HTTP API)** tools: URLs, headers, bodies, bearer tokens, Basic authentication usernames and passwords, API key values, and custom authentication headers.
* The `fetch-url`, `api-call`, `wait-until`, and `paginate-api` flow steps: the same request fields.
* MCP server authentication fields. For details, see [MCP servers](/developer-guides/integrations/mcp-servers).

Managed secrets can't enter custom code, `transform-data` steps, or other user-controlled code. Only external tools accept references. Runtype rejects a reference in any other type of saved tool, including a saved MCP tool, when you save it, and in any other type of runtime tool when you send the request.

Agent Sandbox setup commands are the exception. They can receive secrets as environment variables through a `secretEnv` mapping. Runtype exposes these variables only during setup, and `bash` commands that the model writes never receive them. Run only setup code that you wrote and reviewed, and don't store raw credentials in the sandbox. For configuration, see [Sandbox](/user-guide/agents/creating-and-configuring-agents#sandbox).

If you use an API key to save or run a tool or flow that references a secret, grant the key `SECRETS:READ` or `SECRETS:*`. This applies when you save a tool or flow, dispatch, submit a batch, or run an eval. A key with `*` permission also works. Dashboard sessions need no extra permission. For more information, see [Managing API keys](/user-guide/settings/managing-api-keys).

### Override a secret for an agent alias

If you run an agent through a release alias that binds its own secrets, Runtype uses the alias binding first. For every name that the alias doesn't bind, Runtype uses your account's secret. For example, a preview alias can point its tools at a test environment. For more information, see [Per-alias secret bindings](/user-guide/agents/agent-versioning-and-publishing#per-alias-secret-bindings).

### Request-scoped secrets are not supported

Runtype doesn't support a `secrets` map on agent or flow dispatch requests, and it doesn't resolve `{{secrets.name}}` references. Store each credential as a managed secret and use `{{secret:NAME}}`. A non-empty `secrets` map returns `400` with `RUNTIME_AGENT_TRANSIENT_SECRETS_UNSUPPORTED` for an agent or `RUNTIME_FLOW_TRANSIENT_SECRETS_UNSUPPORTED` for a flow. An empty map does nothing.

## Rotate a secret

Rotating replaces the value and keeps the name. Tools and flows that reference the name use the new value on their next run, and the version increments.

To rotate a secret in the dashboard, follow these steps:

1. Open **Settings > Secrets**.
2. On the secret's row, click **Rotate**.
3. In the **New value** field, paste the value.
4. Click **Rotate secret**.

To rotate through the API, the CLI, or the Runtype MCP server, read the secret's current `version` and send it back with the new value: `expectedVersion` in the API, `expected_version` in the `update_secret` MCP tool. With the CLI, use `runtype secrets update <secret-id> --expected-version <version>` and pipe the value on stdin. Runtype returns `400` if you omit the version and `409` if another change updated the secret first. After a `409`, read the secret again and retry. A description-only update doesn't need a version.

## Delete a secret

Deleting a secret is permanent. Before you delete one, search your tools and flows for `{{secret:NAME}}`. A flow, agent, or tool that references the deleted secret fails on its next run until you remove or replace the reference.

To delete a secret in the dashboard, follow these steps:

1. Open **Settings > Secrets**.
2. On the secret's row, click **Delete**.
3. In the confirmation field, type the secret's name.
4. Click **Delete permanently**. If any of your saved tools reference the secret, the confirmation message reports how many references fail on their next run.

## Check that secrets exist

Before you run a flow or tool, you can confirm that the names it references exist. Use `runtype secrets check <names...>`, the `POST /v1/secrets/check` endpoint, or the `check_secrets` tool on the Runtype MCP server. Each reports which names are found, missing, or revoked.

## When a tool needs a secret

If a tool references a secret that you haven't configured, Runtype reports that the tool needs configuration instead of failing silently. An MCP tool with unresolved secret references returns a configuration-required response with a dashboard URL. The response includes secret names, not secret values.

Open the dashboard URL, add the missing secret, and run the tool again. Enter secret values in the dashboard instead of sending them through chat.

## Troubleshoot

The following errors can occur when you create or update a secret:

* **`409` A secret with this key already exists**: The name is in use. Rotate the existing secret or choose another name.
* **`400` Validation error for the value**: A value must be at least 8 characters so that Runtype can reliably redact it from logs and responses.
* **`403` Insufficient permissions**: The API key lacks `SECRETS:READ` or `SECRETS:WRITE`. Grant the key the missing permission.

## Next steps

Continue with these guides:

* [Creating external tools](/user-guide/tools/creating-external-tools): configure an HTTP tool with a secret reference.
* [Using fetch-url and api-call steps](/user-guide/flows/using-fetch-url-and-api-call-steps): add secret references to flow HTTP requests.
* [Runtime tools](/user-guide/tools/runtime-tools): use secret references in external tools that you define per request.
* [Audit trail](/user-guide/logs/audit-trail): review when secrets were created, changed, or deleted.
* [Connected apps and secret intake](/user-guide/settings/connected-apps-and-secret-intake): review connected apps and fill pending secrets.