Source: docs/integration/token-rotation.md

Capability endpoint token rotation runbook

Endpoint tokens are environment-specific secrets. Use a different token for

development, staging, and production; never copy a staging bundle into

production.

Planned rotation

  1. Generate a new scoped token in the host application's secret manager.
  2. Deploy the host endpoint so it accepts the old and new token during the
    short, documented grace period.
  3. Store the new value with PUT /v1/capability-credentials/{credentialRef}.
    Forgium encrypts it with the environment vault key and never returns it.
  4. Run the current capability contract test and record the capability revision,
    environment, timestamp, and result code.
  5. Confirm a synthetic read or host-interaction preparation reaches the host
    endpoint with the new token.
  6. After the grace period, revoke the old token in the host secret manager and
    verify that it receives 401.
  7. Record the operator, expiry of the grace period, and evidence without
    recording either token.

The update is scoped to the authenticated access bundle and does not change a

capability URL or its revision. If a capability should stop using a credential

immediately, call:

curl -fsS -X DELETE "$FORGIUM_AGENT_BASE_URL/v1/capability-credentials/$CREDENTIAL_REF" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

The response is { "credential_ref": "...", "status": "revoked" }. A revoked

credential blocks new endpoint calls and must be replaced before enabling the

capability for traffic.

Suspected leak

Stop using the affected token, revoke it at the host endpoint, revoke the

Forgium credential, issue a replacement, and inspect the security event trail

for the affected capability. Do not paste the token into tickets, logs, chat,

or a capability manifest. Rotate the Forgium API key or context signing key

separately if either platform secret may also be exposed.

Ownership and evidence

The host application owns endpoint-token generation, endpoint acceptance, and

old-token revocation. Forgium Operations owns vault storage, API-key bundles,

and signing-key publication. Product/Security owns release approval. Evidence

must contain only environment, credential reference, revision, stable result

codes, and timestamps.