Secrets

Field reference for the Secrets page in the Agent Gateway dashboard: its tabs, the Secrets list, secret fields and types, and how to create, update, and delete a secret.

Secrets store encrypted credential values on the gateway so that surfaces and transit points can reference a credential by ID rather than embedding a raw value. Rotating a secret updates every surface that references it, and each surface’s configuration stays as it is.

Overview

A secret holds one encrypted value: an API key, bearer token, password, certificate, or similar credential. Once saved, the raw value stays hidden in the dashboard and in exported configuration. Any configuration that needs the credential references the secret by its Secret ID.

This model means rotating a credential requires updating only the secret. Every surface and element that references that Secret ID uses the new value on the next request, with no surface update required.

Secrets are used in two common surface configurations, and by integration endpoints:

  • Caller authentication (API Key method): the Secret ID field on the API Key source authentication element points to a secret whose value is the expected API key credential. The gateway checks the inbound key against this secret on each request.
  • Transit Point target authentication: the Transit Point’s Authentication section references a secret to inject credentials (bearer token, API key header) into outbound calls to the external destination.
  • Integration endpoints: an endpoint’s SMTP or SASL password, Slack incoming webhook URL, webhook signing secret, or Redis URL can name a secret through Use a stored secret, and a webhook header value can hold $SECRET:<Secret ID>. The gateway reads the secret’s current value at each delivery. See Stored credentials.

For a step-by-step flow that uses a secret for surface access control, see Restrict surface access with API key authentication.

Secrets page tabs

Select Secrets in the sidebar to open the Secrets page. The filter box at the top filters every tab at once.

TabWhat it holds
SecretsEncrypted credential values, described on this page.
API KeysSurface-scoped keys that authenticate external clients. See API keys.
CertificatesClient certificates, filtered by Kind.
Access Tokens (PAT)Personal access tokens for the management API. Shown only to users whose role includes viewing access tokens, which by default is administrators. See Access tokens.

Secrets list

The Secrets tab lists every secret, ten to a page. Select a row to open the secret.

ColumnWhat it shows
NameThe secret’s Secret Name.
Secret IDThe identifier other configuration uses to reference the secret.
DescriptionThe secret’s description, or - when it has none.
TagsThe secret’s tags, or - when it has none.
TypeThe Secret Type.
CreatedWhen the secret was created.
UpdatedWhen the secret was last changed, whether to its value or to its name, description, type, or tags.
ActionsA delete button for the secret.

Fields

FieldRequiredDescription
Secret NameYesA human-readable label, for example OpenAI API key – production.
Secret IDYesGenerated from the name as you type, for example openai_api_key, and editable before the first save. The form shows how other configuration references it, as $SECRET:<Secret ID>. Fixed once the secret is saved.
DescriptionNoNotes shown in the Secrets list, for example the rotation schedule or the issuing service.
Secret TypeYesDescribes the kind of credential. See Secret types below.
Secret ValueYesThe credential value, stored encrypted at rest. Type a value, or select Generate for a random 32-character value of letters, digits, and symbols. After the first save, the field shows Stored value is hidden and the stored value is write-only.
TagsNoFree-form labels for grouping and filtering secrets. Known tags are offered below the field. Adding the sts tag makes the secret appear by default in the STS Client secret picker.

The edit page also has a Metadata card showing Created and Last Updated times.

Secret types

TypeDescription
GeneralA generic credential not covered by more specific types.
ApiKeyAn API key credential.
DatabasePasswordA database password.
CertificateA certificate-type credential. Full certificate objects are managed separately on the Certificates tab of the same page.
SshKeyAn SSH private key.
TokenA bearer token or similar token-type credential.

The type is descriptive only. The gateway stores and injects every value the same way, whatever its type.

Operations

Create a secret

On the Secrets tab, select New Secret. Fill in the required fields and select Create Secret. The Secret ID is generated from the name but can be edited before saving. A Secret ID already in use is flagged on the form.

While you enter or generate a value, Show the value you entered displays it in plain text so you can check it before saving.

Update a secret

Open the secret from the Secrets tab. The stored value stays hidden, so edits to the name, description, type, or tags leave the value unchanged.

To replace the value, tick Update Secret Value, then type a new value or select Generate. Show the value you entered is offered for the new value only, since the stored value is write-only. Clearing Update Secret Value discards the new value.

Save Changes is enabled only when something on the form has changed. After saving, the new value is cleared from the page, and every surface referencing this secret by ID uses the new value from the next request.

Delete a secret

Open the secret and select Delete Secret, or select the delete button on the secret’s row in the Secrets list.

A secret that an integration endpoint uses can’t be deleted. The delete fails with an error notice that names the endpoints using it. Point those endpoints at another value, or delete them, then delete the secret.