Skip to navigation
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 can’t retrieve the existing value.

The following table describes the properties of each secret:

PropertyDescriptionValues
NameThe 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 previewA partial rendering that identifies the secret without revealing its value.Generated from the value.
StatusWhether the secret resolves at runtime.active, needs_configuration (registered without a value), or revoked
VersionA 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
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
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.

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.

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
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.

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.

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.

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.

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: