Completing AI Key Rotation: Save, Verify Calls, Revoke the Old Key

This guide is for organization operators planning an AI API key replacement. It separates issuing the new key, changing the ClawPod Cloud connection, checking real calls, and revoking the old key into distinct completion conditions. You need authority to issue and revoke credentials at the provider and the relevant Credential and Agent permissions in your organization. The procedure follows the public Guide for planned API key rotation; it is not a walkthrough of a verified live interface or a promise of uninterrupted service.

Three distinctions to keep in view

• The model provider issues the API key. Saving a new value in ClawPod Cloud does not automatically revoke the previous key at the provider.
• A successful save, an Agent apply result, and a successful model call are different checks. Verify every connected Agent.
• Planned replacement and suspected exposure are different situations. Do not design a procedure that keeps a suspect key active merely as a recovery option.

Issuing a key and managing its connection are separate responsibilities

A Credential profile is the registration and connection record for authentication information an Agent uses with a model provider or local language model. The public Guide describes this as a ClawPod Cloud Portal function. Do not equate it with changing the Agent Control UI or internal runtime configuration. This article is document-based operational guidance, not a screen guide based on a live Portal inspection.

Create an API key in the provider account or project you intend to use. Set least privilege, budget, and billing conditions at the provider as well. Then register it through the approved Credential input path and connect the target Agents. Do not copy the secret into chat, documents, task comments, logs, or screenshots.

The Guide states that the Portal does not display a stored raw secret again. Use identifying metadata such as the fingerprint and current version to check the target. If a value is lost, issue a new one at the provider and replace it rather than trying to retrieve it. A fingerprint identifies the key; it is not the secret itself. Do not interpret a version as an exact replacement count or a recoverable history. The Guide does not make those guarantees.

A model Credential profile is not a personal password vault or a general-purpose secret store. Work-service passwords and access tokens belong in an available Agent secret store through your organization’s approved transfer procedure. Keep these separate from non-sensitive environment variables such as URLs and project IDs. Additional environment variables are not a secret-storage path.

Record the target, owners, and trigger before making changes

Listing, creating, rotating, applying to an Agent, and deleting may each require different permissions. Access to a screen does not establish permission for every change. If different people own the provider account and ClawPod Cloud changes, decide who passes on verification results and who revokes the previous key.

The following table is an organizational record to fill in, not an automatic product policy.

Decision	What to record	What can go wrong without it
Target	Organization, provider, profile, fingerprint, connected Agent names and count	A different key with the same name may be changed
Owners	Issuing, applying, verifying, and revoking owners, plus deputies	Revocation gets missed after the new key is saved
Trigger	Planned rotation, ownership change, contract end, or suspected exposure	A calendar alone misses incident-driven action
Stop and recovery conditions	Approved change window, work to pause, failure decision owner	Changes are repeated while the apply result remains unknown

A tenant is an organization-level management boundary. The Guide requires the Agent and Credential to belong to the same tenant. When working across organizations, check the organization, provider, fingerprint, and connected Agents, not just the profile name. Centralized authority and team-level ownership are organizational choices. Whichever you choose, name a deputy and a revocation owner.

Planned rotation follows issue → apply → verify → revoke

For a planned replacement with no indication of exposure, follow the Guide’s sequence.

1. Issue the new key. Check the provider account or project and its permissions and budget conditions. Transfer the value only through an approved secret-handling path.
2. Check the impact scope. Inspect the profile fingerprint and the list of connected Agents. An unchanged count does not prove the same Agents are connected.
3. Replace the value in the same profile. According to the Guide, this replacement cannot change the provider, credential type, or profile name. To change provider or type, create a new profile and review the target Agent bindings separately.
4. Check application and real calls. Distinguish updated, pending, and failed, then send a small non-sensitive request to each Agent. If the result is pending or there is a runtime-application warning, first check the Agent state and whether a restart is required.
5. Revoke the previous key after the new connection works. Provider revocation is a separate action. Record who confirmed revocation of which target without recording the secret.

A successful connection test does not guarantee calls will work in the Agent runtime. Conversely, receiving one reply does not by itself prove the new key was used. Check the intended profile binding, the apply result, and each affected Agent’s request result together. If you cannot distinguish the intended connection from a fallback provider or another authentication path, the new-key cutover is still unverified.

A restart is neither always necessary nor always unnecessary. Follow the guidance for the particular change and check the Agent state. The Guide warns that stopping or restarting can affect active work or conversations. For planned changes, the owner should check that work has finished and arrange notice and a change window. Do not assume existing conversations remain unchanged or that every Agent switches at the same moment.

Illustrative example: one of two Agents is still pending

Illustrative example. The request and results below are a sample operational record, not observed execution, a product screen, or an automation feature. They contain no key values or real identifiers.

An operator requests a change record:

Summarize the planned replacement record for summary-model, used by document-summary Agents A and B. Separate the approved targets, each Agent’s apply and test results, and the previous key’s revocation status. Do not request or print secrets. This request does not authorize issuing, replacing, restarting, or revoking anything.

Results supplied by the operator who performed the approved procedure could be organized as follows.

Check	Filled result sample	Assessment
Scope	Example organization’s summary-model, Agents A and B, two total	Organization and target list checked, not name alone
Profile	New fingerprint metadata and current version confirmed; no secret recorded	Save confirmed, not complete cutover
Agent A	Apply result updated; non-sensitive document summary succeeded; intended connection confirmed	A verified
Agent B	Apply result pending; new-connection test not completed	B unverified
Previous key	Not yet revoked; planned replacement with no indication of exposure	Do not report the overall change complete

The operator checks that A and B match the actual affected targets, then inspects B’s state, apply warning, and restart requirement. If a restart is needed, perform it within the approved change window and use the same non-sensitive document to check B’s reply and intended connection. Once B is verified and the provider owner confirms revocation, the final record becomes: “A and B application and calls confirmed; previous key revocation confirmed; owner and time recorded.” Keeping secrets out of the reply is also a success condition.

If B’s call fails, check the Credential binding, Agent settings, restart requirements, and then the provider account, quota, and network state. Inspect errors and logs in a safe test Room without copying sensitive values into shared records. Do not repeat rotation or restart while the outcome is unknown.

Keeping the previous key unrevoked does not mean an automatic recovery button exists. First establish whether the original connection can be restored, whether the previous value was retained through an approved procedure and remains valid, and who authorizes recovery. If recovery is unavailable, pause the work and establish a functioning authentication path again. Do not assume a revoked key can be restored or that the Portal can reveal the original value.

Suspected exposure does not use the planned-change waiting rule

For suspected secret exposure, the Guide instructs operators to replace the value immediately, restart affected Agents, and separately revoke the previous key at the provider. Blindly applying “keep the old key until every test finishes” can leave suspect access active. Have your incident-response owner determine the priority of containment and service interruption. The preceding example is not a waiting instruction for an exposure incident.

When access must end because someone leaves or a contract ends, keep provider revocation as a separate completion condition too. Recording who declares the event and who owns revocation makes omissions easier to find than a rotation interval alone.

Verify profile deletion and provider revocation separately

The Guide requires that no Agent still use a profile before it is deleted. Switch each Agent to another profile or remove its binding, then delete the unused profile. If deletion is refused because the profile is in use, resolve the remaining bindings instead of repeating the delete request.

Deleting a profile does not revoke the provider API key. Verify removal from the list separately from the provider no longer accepting that key for authentication. If you moved to a new profile, verify each target Agent’s new connection and real calls again.

This planned-rotation procedure is limited to API keys. Do not apply it unchanged to Codex sign-in renewal, local model server configuration, or storage encryption-key rotation. The Guide states that Claude setup tokens can be stored but only API keys are allowed for Agent binding, and it does not confirm customer Portal self-service creation, rotation, or recovery of encryption keys.

Before the next change, pick one profile and fill in its affected Agent list, a verification owner for each Agent, and the provider revocation owner. If you cannot fill those three entries, settle the operational responsibilities before changing the key value.

Sources

• ClawPod Guide — AI Key and Credential Management: issuance, permissions, apply results, rotation, and the distinction between deletion and provider revocation.
• ClawPod Guide — Handling Secrets and Sensitive Values: boundaries between model credentials, work secrets, and environment variables.
• ClawPod Guide — Managing Agent State and Settings: post-change verification and restart effects on work and conversations.