# Rotate and revoke credentials

> Roll service-account secrets without downtime, promote the new pair, and revoke access with predictable runtime effect.

Rotate client credentials on a schedule and after any suspected exposure. A
staged credential pair can authenticate alongside the current pair so consumers
can move without downtime; promotion ends the overlap.

## Planned rotation

1. In **Settings → Service Accounts**, open the intended account and start a
   rotation.
2. Capture the new client ID and secret once into the integration's secret
   manager. Do not remove the active pair yet.
3. Deploy the new pair to one canary client.
4. Exchange it at `/api/v1/oauth/token` and make a bounded `api_read` request.
5. Roll the new pair to every client and verify old-client traffic is gone.
6. Promote the staged credentials in Hodoflow.
7. Remove the old pair from every secret store and deployment manifest.

During the overlap, both pairs identify the same service account and therefore
share its workspace, run-as member, scopes, rate budget, and revocation state.
Do not use staging as a way to create a second authorization boundary.

## Token behavior during rotation

Already minted tokens are not an escape hatch. Hodoflow reloads the current
service account and run-as state on each request. Promotion invalidates use of
the old client pair for future exchanges; deactivation or revocation makes
existing tokens fail runtime validation.

Clients should handle a single `401` by discarding the cached token and
exchanging with the currently deployed pair. If exchange also returns
`invalid_client`, stop retrying and alert: the configuration is stale, the
account is inactive, or the rollout was incomplete.

## Emergency revocation

When a secret or token may be exposed:

1. deactivate or revoke the service account immediately;
2. remove the credential from the external system and secret manager;
3. retain non-secret request IDs and audit timestamps for investigation;
4. create or rotate to a new account only after confirming the required
   workspace, run-as member, and least-privilege scopes; and
5. test with the bounded first request before re-enabling automation.

Do not wait for the default 900-second token lifetime. Runtime account
revalidation is designed to make revocation effective sooner.

## Membership and scope changes

Removing `api_write` or `webhooks`, deactivating the run-as membership, or
changing object permissions also affects already minted tokens. Prefer the
narrowest change that addresses the incident, but remember an integration may
cache a token: verify the protected API call, not only the token exchange.

For response handling and correlation, see
[Errors and request IDs](/platform/errors-request-ids). For a reproducible
post-rotation canary, repeat [Make your first API request](/get-started/first-api-request).