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 can’t be changed later, 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.
- Secret Type is chosen from a dropdown (General, ApiKey, DatabasePassword, Certificate, SshKey, Token, or any additional type your appliance’s configuration adds), defaulting to General. ApiKey is used by convention for credentials referenced from a surface’s API key authentication method. The value is descriptive only, with no effect on how the secret behaves.
| Field | Default | Description |
|---|---|---|
| Secret Name | — | Human-readable name. Labeled Secret Name on the dashboard’s create/edit form (not just “Name”). |
| Secret ID | — | Machine-readable identifier used to reference the secret, for example from a surface’s API key authentication method. Must be unique across the store; a create request 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 (see Storage backends below). A comma-separated value is treated as a list of interchangeable credentials by callers that resolve it (see Referencing a secret). Labeled Secret Value on the dashboard’s create/edit form (not just “Value”). |
| Secret Type | “General” | Chosen from a dropdown (General, ApiKey, DatabasePassword, Certificate, SshKey, Token, plus any additional type your appliance’s configuration adds). ApiKey is used by convention for credentials referenced from a surface’s API key authentication method. The value is descriptive only, with no effect on how the secret behaves. |
| Tags | None | Free-form labels; add as many as you need. Secrets can be looked up by tag. |
| 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 bumped only when a create/update request actually changes a field. Shown as Last Updated in the edit page’s Metadata panel. |
Value disclosure
The secret’s raw value is not disclosed uniformly across every read path: the store distinguishes between requests that need the credential and requests that only need to enumerate secrets:
- Create and get by ID both return the full secret record, including the raw value.
- List all and find by tag return the same metadata fields, but with the value omitted entirely.
This means the raw value is retrievable by any caller with access to the get-by-ID endpoint, not exposed 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, Azure, 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 authentication method (see Source authentication) references the secret by its Secret ID, which is resolved against this store at request time.
- Resolution goes through a short-lived, in-memory cache (60-second TTL, keyed by the secret’s ID) so a hot surface does not hit the secrets backend 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 TTL to expire.
Storage backends
Two backends exist, selected by configuration:
- Filesystem (default): secrets are persisted as encrypted JSON files under
_storage/secrets(configurable path). The secret value is encrypted at rest. - AWS Secrets Manager: present as a configuration option but not implemented. Every operation on this backend returns an error directing the caller to use the filesystem backend instead.
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 configured limit is rejected with 403 Forbidden before the store is touched. |
| Update | Fields are updated only where actually supplied and different from the current value, so editing just the Secret Value is enough to rotate a credential without touching anything else on the record. The Secret ID cannot be changed via update. If nothing changed, Last Updated is left untouched and the unmodified record is returned. |
| 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. |
| Find by tag | Filters the metadata list (no values) by exact tag match. |
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 encryption-at-rest guarantee that protects the stored value, and the Backup action that includes it.
- API keys: the managed, per-agent alternative when a single shared secret isn’t enough.
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.