APIZDocs

APIZ guide

Rotate An Upstream Credential Without Redeploying Agents

Use API Instance credential rotation when a provider key expires, is replaced, or may be exposed. Clients route through the API Instance, so a successful rotation changes the upstream credential used by future allowed requests without changing Client Bindings, endpoints, or Temporary Credentials.

Decide What To Revoke

Suspected problemCorrect response
Upstream provider key exposed or expiredRotate the API Instance credential
One agent's APIZ credential exposedRevoke that credential or Credential Group
Every consumer must stop immediatelyDisable the API Instance, then investigate

Rotating an upstream key does not revoke a compromised agent credential.

Web Console

  1. Open the API Instance detail page and select Rotate Credential.
  2. Enter the replacement provider credential in the write-only field.
  3. Run the adapter's configured safe connection test.
  4. Review the redacted request, response, credential fingerprint, and result.
  5. Promote only the tested replacement. A failed test must not silently replace the active credential.
  6. Send a safe agent request and inspect Access Logs.

Ordinary API Instance editing never reloads or resubmits the stored secret. Use the dedicated rotation action.

CLI

read -rsp "Replacement credential: " UPSTREAM_CREDENTIAL && printf '\n'
printf '%s' "$UPSTREAM_CREDENTIAL" \
  | jq -Rs '{credential: .}' \
  | apiz api rotate-secret <api-instance-id> \
      --credential-stdin \
      --confirm-promote
unset UPSTREAM_CREDENTIAL

Credential shapes differ by adapter; use apiz api rotate-secret --help and the corresponding Adapter guide. Then verify:

apiz api test <api-instance-id>
apiz api show <api-instance-id>

Evidence And Recovery

Audit Events should record the actor, API Instance, safe fingerprint change, test/promote outcome, and timestamp without storing either secret. Access Logs after promotion should show normal agent requests using the same Client route.

If the provider supports revocation, disable the old provider key after APIZ promotion succeeds. If impact is uncertain, disable the API Instance first:

apiz api disable <api-instance-id>
apiz api enable <api-instance-id>

Disabling stops all Bindings for that connection; agent credentials may remain valid for their other Bindings.