Skip to main content
Use this maintenance procedure for InternalToken and ScannerToken. Do not use it for the connection-envelope key or third-party integration credentials: those require data migration or provider reconnection, not blind replacement.

​
Prepare the maintenance window

Confirm that the stack is stable, no effect has an unknown outcome, and the operations alert subscription is confirmed. Record the current secret version IDs and service/runtime revisions without recording secret values. Keep the AWSPREVIOUS version until the new ECS and AgentCore revisions pass health checks. The script performs a rolling replacement. Brief internal authorization failures are possible while old and new tasks overlap, so pause new operator work before proceeding.

​
Authorize one rotation

The script retrieves fresh values from Secrets Manager, writes new secret versions without printing them, forces replacement of web, worker, and scanner tasks, recreates the AgentCore runtime revision from its current reviewed configuration, and waits for every replacement to become ready. Stop immediately if any required stack output is absent, AgentCore returns FAILED, ECS does not stabilize, or health checks report authorization failures after the replacement deadline.

​
Verify the rotation

Run the following checks through normal interfaces:
  1. Load /api/health through the public load balancer.
  2. Submit a read-only chat status request and confirm the worker-to-web callback succeeds.
  3. Upload the licensed scanner fixture and confirm the scanner-to-web authorization succeeds.
  4. Invoke a read-only AgentCore specialist request and confirm the new runtime reaches the private web service.
  5. Confirm that no old task definition or runtime version remains active.
Record only secret ARNs, version IDs, task-definition revisions, runtime version, health outcomes, timestamps, and the approving operator. Never retain secret values.

​
Recover a failed rotation

If the new version fails, promote the recorded AWSPREVIOUS version back to AWSCURRENT, force the same ECS and AgentCore replacements, and repeat the health checks. Do not improvise a second secret value while the outcome of the first replacement is unknown.
Last modified on September 14, 2026