Settings

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 cannot retrieve the existing value.

Each secret has these properties:

  • Name: Reference the name in tool and flow configurations. Runtype stores names in uppercase. Use 2 to 100 characters, start with a letter, and use letters, digits, and underscores. For example, STRIPE_API_KEY.
  • Masked preview: Identify the secret without revealing its value.
  • Status: Check whether a value-bearing secret is active or revoked. A registered secret without a value is needs_configuration.
  • Version: Track rotations with the version. A value-bearing secret starts at version 1. A pending secret starts at version 0. The version increments each time you rotate the value.

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. Use at least 8 characters.
  5. Click Save secret.

After you save the secret, Runtype encrypts the value and shows only its masked preview.

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
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 does not enter model context or the returned response.

Managed secrets work in External (HTTP API) tools and HTTP-capable flow steps. Supported step types include fetch-url, api-call, wait-until, and paginate-api. Use references in URLs, headers, bodies, bearer tokens, Basic authentication usernames and passwords, API key values, and custom authentication headers.

Managed secrets cannot enter custom code, transform-data steps, or other user-controlled code paths. For runtime tools, Runtype allows references only in external tools and rejects them in other tool types when you save the configuration.

Agent Sandbox is an exception for operator-authored setup commands. With an explicit secretEnv mapping, Runtype exposes the credential environment only during setup, not to model-authored bash commands. Keep setup code operator-authored and reviewed. Do not run model-, attacker-, or supply-chain-authored code when credentials are present. Do not persist raw credentials. Prefer credential proxies when the protocol supports them so the real credential does not enter the sandbox.

If an API key handles an HTTP Flow step configuration with a secret reference, grant it SECRETS:READ or SECRETS:*. This requirement applies when you create, update, or ensure a Flow, dispatch an inline Flow, submit a batch, or submit an Eval. An API key with * permissions also passes this check. Dashboard sessions do not need an API key permission to use managed secrets in supported HTTP fields.

{{secret:NAME}} and {{secrets.name}}

These syntaxes look similar, but they use different sources and lifetimes. The following table compares them:

SyntaxSourceLifetime
{{secret:NAME}} (colon)Your account’s managed Secrets storePersistent. Manage it in Settings > Secrets.
{{secrets.name}} (dot)A caller-supplied map on the dispatch request (retired)Ephemeral, and refused on both dispatch targets.

Use {{secret:NAME}} for every credential. The request-scoped secrets map is retired on BOTH dispatch targets. A non-empty map is refused with a 400 that tells you to store the value as a managed secret: RUNTIME_AGENT_TRANSIENT_SECRETS_UNSUPPORTED on an agent dispatch, RUNTIME_FLOW_TRANSIENT_SECRETS_UNSUPPORTED on a flow dispatch. An empty map is accepted and does nothing.

There is no longer an exception. The options.useRuntimePackage: false opt-out that used to run a dispatch on the legacy engine, which still resolved {{secrets.name}} for single-turn agents, is itself refused: that engine has been retired. Store the value in Settings > Secrets and reference it as {{secret:NAME}}.

Rotate, revoke, or delete a secret

Use these actions to manage a secret:

  • Rotate: Replace the value and keep the same name. Tools and flows that reference the name use the replacement value on their next execution. The version increments.
  • Revoke: Mark the secret inactive. Runtype no longer resolves it.
  • Delete: Remove the secret. A flow, agent, or tool that references the deleted secret fails on its next run until you remove or replace the reference.

When a tool needs a secret

If a tool references a secret that you have not 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.

Next steps

Continue with these guides: