Rotate and revoke credentials

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. For a reproducible post-rotation canary, repeat Make your first API request.