Gateway Credential Rotation

Rotate the gateway auth token and instantly revoke every live session that was authenticated under the old secret

Rotate the shared gateway secret and every already-connected client using the old token is force-closed within one reload cycle — no full process restart, no leaked credential left trusted.

An agent connects through the gateway; if the operator later rotates the secret, the agent’s client is told to re-authenticate rather than back off.

from praisonaiagents import Agent

agent = Agent(name="Ops Agent", instructions="Report status", gateway=True)
agent.start("ping")
# If the operator rotates the gateway secret, this agent's client will receive
# WebSocket close (4001, "credentials_rotated") and should re-authenticate.

Quick Start

1. Rotate the token in gateway.yaml

   # gateway.yaml
   gateway:
     auth_token: "${GATEWAY_AUTH_TOKEN_NEW}"     # was: ${GATEWAY_AUTH_TOKEN_OLD}
     revoke_on_secret_rotation: true              # default; shown for clarity

2. Trigger the hot-reload path

   File watch picks the change up automatically, or send SIGHUP:

   kill -HUP "$(pgrep -f 'praisonai serve gateway')"

   Every WS session that authenticated under the old secret closes with code 4001 and reason credentials_rotated. Sessions already on the new secret stay connected.

How It Works

At connect time the gateway stamps each authenticated session with a truncated SHA-256 fingerprint of the active secret. When the reload path notices a new auth_token, it adopts it and closes every session whose stamp doesn’t match the new fingerprint. Sessions on the new secret are left untouched. The raw secret is never logged — only the digest.

The CREDENTIALS_ROTATED close reason is described in the SDK as:

The shared gateway secret this session authenticated under is no longer the active secret (an operator rotated auth_token and hot-reloaded, or otherwise revoked it). The server force-closes every session stamped with a stale secret so a leaked/revoked credential stops working within one reload cycle, without a full process restart. Clients should re-authenticate and reconnect with fresh credentials rather than backing off as if the server were down.

Configuration

gateway:
  auth_token: "${GATEWAY_AUTH_TOKEN}"
  revoke_on_secret_rotation: true   # default

Rotation Behaviour — Decision Matrix

When does rotation actually happen?

Client-Side — How to Re-authenticate

Force-closed sessions receive:

Treat (4001, "credentials_rotated") as “re-authenticate with fresh credentials” — not as “server is down, back off”. A well-behaved client:

1. Reads the new secret from its own credential source (env, secrets manager, praisonai auth login).
2. Reconnects immediately with the new token.
3. Reports back to the operator if the fresh token also fails.

ws.addEventListener("close", (event) => {
  if (event.code === 4001 && event.reason === "credentials_rotated") {
    const token = process.env.GATEWAY_AUTH_TOKEN;   // freshly rotated secret
    reconnectWithToken(token);                        // re-auth, do NOT back off
  }
});

Security Notes

• The raw auth_token is never logged, exported, or persisted by this feature — only a 16-char truncated SHA-256 stamp is kept per session for comparison.
• When rotation adopts a new secret, it also updates GATEWAY_AUTH_TOKEN in the environment so all auth paths (HTTP, magic-link, WS) read the same value — matching Bind-Aware Auth (config wins over env).
• If auth_token is declared but resolves to empty (e.g. an unset ${VAR}), the previous secret is kept and a warning is logged instead of silently clearing auth.
• Loopback-only gateways (no auth_token) map to the sentinel "no-auth" — rotation is meaningless in that mode.

Common Patterns

Scheduled quarterly rotation

gateway:
  auth_token: "${GATEWAY_AUTH_TOKEN_Q3_2026}"
  revoke_on_secret_rotation: true

Rotate the referenced env var and reload — old sessions disconnect, clients re-auth with the new secret.

Suspected leak — revoke now

export GATEWAY_AUTH_TOKEN_NEW="$(openssl rand -hex 32)"
sed -i 's/GATEWAY_AUTH_TOKEN_OLD/GATEWAY_AUTH_TOKEN_NEW/' /etc/praisonai/gateway.yaml
kill -HUP "$(pgrep -f 'praisonai serve gateway')"

Every session on the leaked secret is disconnected within one reload cycle.

Coordinated cutover — adopt now, evict later

gateway:
  auth_token: "${GATEWAY_AUTH_TOKEN_NEW}"
  revoke_on_secret_rotation: false   # give clients a grace window

Later, flip revoke_on_secret_rotation back to true and reload to evict any laggards still on the old secret.

Best Practices

Related