Settings

Managing secrets

Secrets are a secure, central place to store credentials — API keys, tokens, and other sensitive values — that your external tools need. You register a secret once under a name, then reference it by that name from any external tool. Runtype resolves the value at runtime and never exposes it to the AI model, the response, or your logs.

How secrets work

A secret is a named value stored encrypted in your account. Secrets are write-only: once you save one, the dashboard and API never return its value again. You only ever see a masked preview (for example, the last few characters) to help you identify it. To change a value, you rotate it — you cannot read the existing one back.

Each secret has:

  • A name that you reference in tools. Names are unique within your account and must be uppercase letters, digits, and underscores, start with a letter, and be 2-100 characters (for example, STRIPE_API_KEY).
  • A masked preview so you can tell secrets apart in the list.
  • A status of active or revoked, and a version that increments each time you rotate the value.

Secrets are encrypted at rest, resolved only inside the tool that uses them, and scrubbed from streamed events, stored results, and logs.

Add a secret

  1. Go to Settings → Secrets.
  2. Click Add Secret.
  3. Enter a name (for example, STRIPE_API_KEY) and paste the value.
  4. Save.

The value is encrypted immediately. After saving, only the masked preview is shown.

Reference a secret in HTTP integrations

Use the {{secret:NAME}} syntax wherever an external HTTP integration accepts text — URLs, headers, bodies, and structured auth fields:

Authorization: Bearer {{secret:STRIPE_API_KEY}}
X-API-Key: {{secret:SERVICE_KEY}}

At execution time, Runtype substitutes the stored value directly into the outgoing HTTP request before anything else runs. The value never enters the model’s context, so the AI cannot see or repeat it.

Managed secrets work in external (HTTP) tools and HTTP-capable Flow steps: fetch-url and api-call, wait-until polling requests, and paginate-api. In these steps, you can reference secrets in URLs, headers, bodies, bearer tokens, basic-auth usernames/passwords, API-key values, and custom auth headers. They are intentionally blocked from custom code, transform-data steps, and non-HTTP tool types so a credential can never be read by code you control. If you add a {{secret:NAME}} reference to a tool or step type that doesn’t support it, the save is rejected.

API keys that create, update, ensure, inline-dispatch, batch-submit, or eval-submit HTTP Flow step configs containing {{secret:NAME}} must include SECRETS:READ (or SECRETS:*). Dashboard sessions are scope-free and can use managed secrets in supported HTTP fields.

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

These look similar but are different mechanisms:

SyntaxSourceLifetime
{{secret:NAME}} (colon)Stored in your account’s Secrets storePersistent — managed in Settings
{{secrets.name}} (dot)Passed in the secrets field of a dispatch requestEphemeral — only for that request

Use {{secret:NAME}} for credentials you manage once and reuse. Use {{secrets.name}} when a developer supplies a per-request value through the API or SDK, such as a per-user token in a multi-tenant app.

Rotate, revoke, and delete

  • Rotate — replace the value while keeping the same name. Every tool that references it picks up the new value automatically, and the version increments.
  • Revoke — mark a secret inactive so it can no longer resolve.
  • Delete — remove the secret entirely.

Tools that need a secret

If a tool references a secret you haven’t configured yet, Runtype marks the tool as needing configuration rather than failing silently. When this happens through an MCP client, the tool returns a configuration-required response with a link to the dashboard, so the credential is never requested through the AI model. Open that link, add the missing secret, and the tool resolves normally on the next run.

Next steps