API keys
Agent Stream’s API Key Provider issues and manages agent-scoped API keys that a caller presents to authenticate against a surface’s API Key Provider authentication method. This page documents the key record, its lifecycle, and how it differs from a plain secret. For the conceptual model, see Security and access control.
API key record fields
A managed key ties directly to one agent and carries its own expiry, rotation history, and audit trail. That makes it easy to hand a caller a credential you can time-box and revoke without touching anything else the agent uses.
- Expires should be a real duration for any key handed to an external caller or used in a short-lived integration. Reserve Never for keys you’ll actively track and rotate yourself.
- Labels double as the ownership record: there’s no separate owner field beyond Client ID, so labels are what let you tell keys apart later.
- A Rotate required badge means the key predates hashed-secret storage and can no longer authenticate, regardless of what its status says. Rotate it.
The full stored record:
| Field | Default | Description |
|---|---|---|
| Key ID | Generated automatically | Unique identifier, prefixed atgk_ followed by a UUID v4 (simple form), e.g. atgk_a1b2c3.... |
| Agent ID | — | The agent this key belongs to; keys are scoped and validated per agent. Labeled Agent ID in the create-key form. The same value is displayed under different labels elsewhere in the dashboard: Surface in the Secrets page’s API Keys list (resolved to the surface’s name), and Channel in the key detail page. |
| Client ID | — | External client identifier associated with the key, entered as text. |
| Status | Active | Current key status; see Status values below for what each one means. A key created before hashed-secret storage existed has no usable secret and can no longer authenticate, even though it still shows as Active. The dashboard flags this with a Rotate required badge next to the status and a warning banner on the key detail page: rotate the key to restore access. |
| Created | — | Set at creation. Shown as Created in the key list tables and the detail page’s Metadata panel; the one-time key-creation modal instead labels it Created At. |
| Expires | Never | When the key stops authenticating. The dashboard shows Never when no expiry is set. Shown as Expires (not “Expires At”) in the key list table. |
| Revoked | Not set | Set when the key is revoked. Shown as Revoked (not “Revoked At”) in the key detail page’s Metadata panel. |
| Last Used | Not set | Updated best-effort on successful validation; not guaranteed to be precise under concurrent use. Shown as Last Used (not “Last Used At”) in the key list table and detail page. |
| Labels | None | Free-form key/value labels for categorisation; add as many as you need. |
| Issuer | — | Audit trail recording who issued the key (the actor) and how it was created: a direct API call, a rotation, a migration, and so on. |
| Rotated From | None | If this key was created by rotating another, the old key’s ID. |
The one-time creation/rotation response additionally carries the raw key material as API Key Secret / Secret, disclosed only in that response and never retrievable again. The stored record itself never carries a readable version of it.
Key and secret format
- Key ID:
atgk_followed by a UUID v4 in simple (no-hyphen) form. - Secret:
atgs_followed by a URL-safe, unpadded base64 encoding of 32 CSPRNG-generated bytes (256 bits). - The secret is hashed with SHA-256 for storage and validated with a timing-safe (constant-time) comparison. Since the secret itself is a 256-bit random token, a fast one-way hash is sufficient: brute-forcing the pre-image is infeasible.
Status values
A key’s status is one of two values. The key detail page shows it as a capitalized word (Active / Revoked); the API keys list table shows the same value unstyled, lowercase:
| Status | Meaning |
|---|---|
active | Can authenticate, subject to expiry. |
revoked | Cannot authenticate. Revocation cannot be undone; a revoked key cannot be re-activated (only rotation or creating a new key restores access). |
A key past its expiry date stops authenticating immediately, even though its status still shows Active / active: expiry is checked at the moment the key is used, not tracked as a separate status.
Expiry and rotation
Rotation is what makes it safe to hand out a long-lived credential in the first place: you can issue a new secret on the same schedule without changing the key’s identity, expiry countdown, or anything that references it by Client ID.
- Rotate on a schedule instead of setting a very long expiry. Rotation preserves the key’s remaining lifetime, so the new key keeps counting down from wherever the old one left off rather than resetting the clock. A key with no expiry stays that way after rotation too.
- Rotate, rather than delete-and-recreate, when a key might be compromised or is due for periodic refresh. The old key is revoked immediately, and the new one carries Rotated From for the audit trail. You can’t rotate a key that’s already revoked; create a new one instead.
- Delete a key only when you want it gone from the record entirely; rotating it is enough if you just want the old secret invalidated while keeping the history.
Using a managed API key for source authentication
A surface authenticates callers against this store via the API Key Provider authentication method, which pairs an API Key Location rule (where the key is read from on the request) with an agent ID. The presented key is validated against that specific agent’s keys, and a match resolves to the caller’s identity.
This is distinct from the plain API key method, which validates against a secret by ID rather than a managed, per-agent, rotation-aware key record. That difference is what lets you issue each caller their own scoped, revocable credential instead of sharing one static secret across everyone who calls a surface.
- The API Key Provider is worth the extra setup when you need per-caller expiry, rotation, revocation, or an audit trail: for example, issuing a distinct key to each external integration.
- Use a plain secrets-store API key when a single shared credential is enough and you don’t need per-key lifecycle management.
Creating a key is subject to the appliance’s API-key count limit, checked against both the limit on managed API keys 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.
Related
- Secrets: the plain-credential alternative to the API Key Provider.
- Source authentication: the API Key Provider and API key methods, and the identity a successful match produces.
- RBAC: the permissions that gate this store, Administrator-only by default.
- Security and access control: the conceptual grounding for managed API keys.
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.