Rotate provider credentials without downtime

Point a surface’s LLM node at a new secret holding the new provider credential, confirm it works, then retire the old secret, so every surface keeps working while you rotate.

This guide rotates the API key a surface uses to authenticate to its own upstream LLM provider: the credential referenced by the LLM node’s API Key Secret field. It works by creating a new secret and repointing the surface at it, so no surface ever sees a moment with no valid credential. For the conceptual model, see Security and access control →.

A secret’s value has no dedicated “rotate” operation the way a managed API key does. For a surface’s inbound caller authentication (the source authentication API key method, which checks a caller-presented key against a secret’s value), a comma-separated value genuinely is split into a list of interchangeable credentials, so holding old and new values side by side in one secret works there. See Source authentication reference. The LLM node’s API Key Secret is the opposite direction: the surface sends that secret’s stored value to the provider verbatim, with no comma-handling at all. Editing it to a comma-joined old-key,new-key value would send that literal string to the provider as the API key and fail every request through the surface, not rotate anything. Rotating an outbound provider credential without downtime instead means creating a new secret for the new credential, repointing the LLM node at it, confirming it works, and only then retiring the old secret.

Use this guide when:

  • A provider credential (the key a surface uses to call its own upstream LLM provider) needs to change on a schedule, or in response to a suspected leak, without an outage while surfaces switch over.
  • More than one surface references the same secret, so every one of them needs to move to the new credential before the old one is revoked.
  • You want to confirm the new credential works before revoking the old one, rather than the other way around.

You do not need this if only one surface references the credential and a short window of failed requests during the switch is acceptable; updating the existing secret’s value directly is simpler.

Prerequisites

  • Administrator role in the dashboard; secrets management (viewing, creating, editing, and deleting a secret) is administrator-only by default.
  • A newly issued credential from the provider, generated before you touch any secret.
  • Every surface’s Secret ID, as referenced from its LLM node’s API Key Secret field, for each surface that uses the credential you’re rotating.

Steps

Generate the new credential on the provider’s side

Create the new credential with your provider first, without revoking the old one yet. Keep both available for the next steps.

Create a new secret for the new credential

The New Secret creation form, with a distinct Secret Name entered and the Secret Value field revealed showing the new credential

Select Secrets in the dashboard sidebar, then select New Secret. Give it a distinct Secret Name so it’s easy to tell apart from the one it replaces, and set Secret Value to the new credential. Select Save, then note the new Secret ID. Leave the old secret’s value untouched for now.

Point the LLM node at the new secret

Under SURFACES in the dashboard sidebar, select LLM, open a surface that references the old secret, and select its LLM node. Set API Key Secret to the new secret in place of the old one, then select the save icon in the toolbar. The change applies immediately; no restart is required.

Repeat this step for every other surface that references the old secret.

Confirm every surface still succeeds

Send a request through each surface you just repointed. A surface’s LLM node change takes effect as soon as it is saved, so the next request already authenticates with the new credential.

Delete the old secret once every surface is confirmed

Once you have confirmed successful traffic from every surface that used to reference it, re-open the old secret’s page and delete it.

Revoke the old credential on the provider’s side

Only now revoke or delete the old credential with your provider. No surface references it anymore, so revoking it no longer affects any live traffic.

Confirm

Replace <YOUR_APPLIANCE_HOST> and <YOUR_SURFACE_ROUTE> with your surface’s values.

Test 1: a request returns 200 immediately after repointing the LLM node

curl -k -X POST "https://<YOUR_APPLIANCE_HOST><YOUR_SURFACE_ROUTE>/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Say hello after rotation." }
    ]
  }'

The -k flag disables TLS certificate verification. Use this for local testing only. Remove it in production.

Send this immediately after saving the surface in step 3, without waiting. Expected: 200 OK, confirming the new secret authenticates correctly with the provider as soon as the LLM node change is saved.

Test 2: traffic still returns 200 after the old secret is deleted

After completing step 5, resend the same request. Expected: 200 OK, confirming the surface no longer depends on the old secret at all, before you revoke its credential with the provider.

Troubleshooting

SymptomLikely causeFix
Requests start failing right after the old secret is deleted.A surface’s LLM node was never actually repointed at the new secret before deletion, or a different surface altogether still references the old secret’s ID.Re-open each surface’s LLM node and confirm its API Key Secret names the new secret, then repeat steps 3–4 for it.
A secret’s value looks unchanged when you re-open it.Listing or tag-search views never return a secret’s raw value by design; only the get-by-ID view and the edit form show it.Open the secret directly by its own edit page, not a list or search view, to see the current raw value.
A surface still fails after every step above.The new credential itself is invalid or was revoked at the provider, independent of anything in Agent Stream.Confirm the new credential authenticates directly against the provider, outside Agent Stream, before troubleshooting further here.
A surface still uses the old credential after you saved it.The LLM node’s API Key Secret field was left unchanged, or the save did not apply.Re-open the surface, confirm API Key Secret now names the new secret, and select the save icon again.

Next steps