Rotate credentials

# Rotate credentials

Canonical: https://docs.flowrelay.app/setup/rotate-credentials/
Markdown: https://docs.flowrelay.app/setup/rotate-credentials.md

Rotate an endpoint secret deliberately. FlowRelay shows the new full secret once and never reveals the previous full secret.

## Steps
Complete these in order.
1. Open the endpoint
   Open Endpoint setup for the sender that needs a new secret.
2. Coordinate with the sender owner
   Confirm the sender owner is ready to update their private configuration immediately after rotation.
3. Rotate and store the new secret
   Choose a generated or sender-owned credential and an overlap of none, one hour, or 24 hours. Review and confirm. Copy a generated value once into the sender's private secret manager; enter a sender-owned value only in the private confirmation form.
4. Retire the previous secret
   Check the current and previous key last-used times. Revoke the previous key as soon as the sender has moved; otherwise it expires at the selected deadline. A second rotation replaces any older overlap, keeping at most two credentials.
5. Verify the new credential
   Send one test event with synthetic data and open the receipt to confirm authentication succeeds.
6. Share only safe evidence
   Share only the receipt outcome or diagnostics share if troubleshooting is needed. Do not paste the new secret, old secret, full authentication header, or signature into support.

## When to rotate
Rotate when a secret may have been exposed, a partner no longer needs access, a sender changes ownership, or an operator wants a clean credential handoff.


## What changes
The endpoint URL stays the same. Generated credentials are shown once; repeated execution returns the saved result without revealing a secret again. Expired or revoked credentials are rejected on subsequent requests. The emergency immediate-rotation control invalidates both the old current and previous credentials. Treat an exposed key as compromised and select no overlap.


## Agent boundary
An authorized agent may prepare or execute a rotation only when the grant includes the required scope. It still cannot retrieve old secrets, Shopify tokens, session data, raw event bodies, or database credentials.


## Related
- [Authenticate requests](https://docs.flowrelay.app/setup/authentication.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.