Rotate an AI integration API key with an inventory and revocation check

Inventory consumers before replacement

Start with a credential inventory that records key ID or safe prefix, owner, workspace, intended consumer, scopes, expiry, storage location reference and operational contact. Record the location of a secret, never its value. Distinguish a key used by a reporting job from one used interactively. A key with no identified consumer is an unresolved inventory item, not automatically safe to leave active. Evidence of recent use can help, but lack of use is not a complete dependency map.

AdAce Ads stores a key hash, displays the full key only at creation and evaluates its scopes together with the owner's current permissions. Rotation should preserve or reduce the required boundary, not add propose scope merely because a new key is being issued. For a reporting-only task, use the intended read capability. An API key and an OAuth grant are different credentials; replacing one does not replace or revoke the other. Identify the actual authentication path before beginning.

A teaching example has two consumers: a report preparation script and a temporary analyst session. The script needs a planned replacement; the temporary session has ended and should be closed rather than migrated. The runbook records one cutover and one removal. It does not copy the same replacement into every known device. An unidentified consumer using the old identity after cutover is a reason to investigate, not to restore the old key indefinitely for convenience.

Cutover and revocation need separate checks

• Choose the rotation mode from the reason. Routine replacement can allow a short controlled overlap when supported; suspected exposure may require immediate revocation and temporary service interruption. Do not assume continuity is more important than containment.
• Use a verification matrix with old credential, replacement credential and affected consumers. A successful replacement read proves only that read path. It does not prove that the old credential is revoked or that every scheduled consumer was updated.
• Keep identifiers and timestamps in the runbook, not screenshots of secret fields or authentication headers. A rotation report should be useful to another operator without becoming a new distribution channel for credentials.

Replace, verify and close

1. Identify the owner and all documented consumers. Review required scopes and client access, then choose routine or emergency handling. Record the authorized cutover owner and the condition for ending any overlap period.
2. Provision a replacement through the existing authorized key workflow if replacement is required. Check current account limits and permissions instead of hardcoding them in the runbook. Store the new value directly in the approved secret location without pasting it into notes, chat or logs.
3. Update one controlled consumer and verify a harmless permitted read in the intended workspace. Confirm that it reads the right scope and does not invoke propose_change or any write tool. Repeat the consumer-specific check where credentials or execution environments differ.
4. Revoke the old key through the authorized control and confirm that an isolated old-credential read is rejected. Use secure tooling that hides request headers and the secret. Do not put the credential into a shell command, URL, screenshot or exported test report.
5. Close the rotation with safe evidence: replacement ID, old ID, consumer checks, revocation result, verifier and time. Watch for failed consumers using the former credential and resolve them by proper migration or closure. A revoked secret must not become the recovery mechanism.

Know which credential boundary changed

Sources and further reading

• AdAce Ads API key behavior
• AdAce Ads connection activity
• AdAce Ads audit log