> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# How to rotate internal service tokens

> Rotate Harmonia's generated service tokens and replace every runtime that consumes them.

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

```bash theme={null}
export HARMONIA_ALLOW_PAID_DEPLOYMENT=true
export HARMONIA_APPROVE_SECRET_ROTATION=rotate-internal-service-tokens
export HARMONIA_STAGE=staging
infra/rotate-service-secrets.sh
```

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.