# Secrets

Supply hidden configuration to Workflows, with separate lifecycles for manually entered values and Credential-managed tokens.

Last updated: 2026-10-18

A Secret holds a hidden configuration value for an Environment, such as an API key or token. A
Workflow refers to it as `secrets.NAME`, for example `secrets.API_TOKEN`.

Use a [Variable](/configuration/variables) for configuration that can be read back normally.
Secret management tools return metadata about a Secret, rather than its value.

## Two ways a Secret gets its value

| Source | How it is maintained |
| --- | --- |
| A value you enter directly | Replace it when the issuing service changes or rotates it |
| A [Credential](/configuration/credentials) | Typenode maintains the authorized account's access token |

A Workflow uses `secrets.NAME` in both cases. A Credential-managed Secret cannot be overwritten
through the ordinary manual Secret update path. Manage its account authorization through the
Credential.

## Scope and Workflow access

A Secret name belongs to the Workspace, while its value belongs to an [Environment](/configuration/environments). A name has one
kind throughout the Workspace: it cannot be a Secret in production and a Variable in staging.

Secret configuration is shared within the Environment. It is not owned by one Workflow. A Workflow
that references the Secret uses the selected Environment's value, subject to Typenode's access and
configuration checks.

For example, `secrets.API_TOKEN` can represent different service accounts in staging and production.
Setting up the staging value does not populate the production value.

## Supplying a sensitive value

When an Agent prepares Secret setup, enter the value on the Typenode page provided by the handoff.
The Agent can check whether setup completed without receiving the value in the Secret management
response.

Secrets are protected in storage and made available for authorized runtime use. Hidden management
responses do not make a Secret safe to include in a Workflow's output or send to an unintended
service. [Sensitive data and handoffs](/agents/sensitive-data) explains the protection and
runtime boundaries.

## Changing a Secret

Later Runs use updated Secret values without republishing the Workflow. Rotation does not replace
every request already in progress. Each new Run attempt loads current Secrets. Requests already
prepared keep their original Secret version, and a Run that resumes after waiting can continue
within the same attempt.

For example, replacing an API key while a Run waits does not guarantee that the Run will use the
replacement when it resumes. Keep the old key valid at the service for as long as in-progress work
needs it, unless the key must be revoked immediately.

Plan a rotation around the outside service's rules for old and new credentials. Changing a stored
value in Typenode does not itself rotate the API key at the issuing service.

## Missing and empty values

A registered name does not guarantee a usable value in the chosen Environment. Reading an absent
Secret in Workflow code fails with a missing-configuration error. Manual Secret values cannot be
empty. Configuration checks can also reject missing required values before a Run starts.