Secrets
Agent Stream’s secrets store holds provider API keys and other credentials so a surface’s source authentication or provider configuration can reference a credential by ID rather than embedding it directly. This page documents the stored secret record, how its value is disclosed, and its create/update/delete lifecycle. For the conceptual model, see Security and access control.
Secret record fields
Every secret is a named credential you create once and reference by ID, from a surface’s API key authentication method or a provider configuration, rather than pasting the raw value anywhere else. That keeps the value in exactly one place, so secret rotation for a compromised or expiring credential means a single edit here instead of a hunt through every configuration that uses it.
- Pick a Secret ID you’re comfortable keeping. It is generated from Secret Name until you edit it, and it can’t be changed after the secret is created, so renaming means creating a new secret and re-pointing everything that referenced the old one.
- If more than one credential should work interchangeably (for example, rotating in a new provider key before retiring the old one), enter them as a single comma-separated Secret Value; either one will authenticate.
- Set Secret Type to ApiKey for a secret a surface’s API Key (secret store) authentication method will check against: that method’s Secret picker lists only secrets of type ApiKey or with no type.
| Field | Default | Description |
|---|---|---|
| Secret Name | — | Human-readable name. |
| Secret ID | Generated from Secret Name | Machine-readable identifier used to reference the secret, for example as $SECRET:<secret_id> or from a surface’s API key authentication method. Uses 1 to 256 letters, digits, hyphens, underscores, or full stops, and can’t contain ... Must be unique across the store; creating a secret that reuses an existing Secret ID is rejected. |
| Description | Not set | Optional free-text note. |
| Secret Value | — | The credential value, entered as text. Encrypted at rest. A comma-separated value is treated as a list of interchangeable credentials by callers that resolve it (see Referencing a secret). |
| Secret Type | General | Chosen from a dropdown (General, ApiKey, DatabasePassword, Certificate, SshKey, Token, plus any additional type your appliance offers). The type decides which pickers offer the secret: the API Key (secret store) method’s Secret picker lists secrets of type ApiKey and secrets with no type. |
| Tags | None | Free-form labels; add as many as you need. The Secrets page’s search also matches tags. |
| Created | — | Set at creation. Shown as Created in the secret list table and in the edit page’s Metadata panel. |
| Last Updated | — | Set at creation and updated only when a save actually changes a field. Shown as Updated in the secret list table and as Last Updated in the edit page’s Metadata panel. |
Value disclosure
The Secrets page lists each secret’s metadata but never its value. Opening a secret’s edit page loads its stored value, masked until you select Show secret value, so the raw value can be read back after creation, not only at creation time. Secrets management is Administrator-only by default (see RBAC), which is what actually restricts who can read a value back.
Referencing a secret from a surface
This is where a provider’s own API key gets used: create a secret here holding the credential you got from OpenAI, Anthropic, or whichever provider you’re connecting to, then point a surface at it by Secret ID instead of pasting the raw value into the surface’s own configuration. A surface never embeds a raw credential value directly.
- A surface’s API Key (secret store) authentication method (see Source authentication) references the secret by its Secret ID, which is resolved against this store at request time.
- Resolved values are cached for up to 60 seconds, so a busy surface doesn’t look up the secret on every request. A comma-separated value is split into a list of individually valid credentials: any one of them matches.
- Updating or deleting a secret evicts its cache entry immediately, so a rotated value takes effect without waiting for the cache to expire.
CRUD lifecycle
| Operation | Behaviour |
|---|---|
| Create | Rejects a duplicate Secret ID. Subject to the appliance’s secret-count limit, checked against both the limit on secrets specifically and the overall limit across every credential type in the store. A create that would exceed a limit is rejected before the store is touched. |
| Update | Only fields that actually change are updated, so editing just the Secret Value (with Update Secret Value ticked) is enough to rotate a credential without touching anything else on the record. The Secret ID can’t be changed. If nothing changed, Last Updated is left untouched. |
| Delete | Removes the secret and evicts it from the resolution cache. No soft-delete or rotation-preserving behaviour: deleting a secret that a live surface still references will fail that surface’s requests at runtime. |
There is no dedicated “rotate” operation for a secret the way there is for a managed API key. Rotating a secret is done by editing its value and saving, and every surface referencing it picks up the new value on its next request once the cache entry is evicted.
Related
- Security and access control: the conceptual model for secrets, source authentication, and RBAC together.
- Source authentication: the API key authentication method, which references a secret by its Secret ID.
- RBAC: the permissions that gate this store, Administrator-only by default.
- Backup and encryption: The Backup action, which includes secrets.
- API keys: the managed API key records that the API Key (provider) method checks against.
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.