Manage credential renewal and revocation

Replace or revoke OpenClaw Control Plane (OCC) service keys, provider credentials, and runtime Secrets. First identify the credential's owner and every application or Agent that uses it. After replacing a credential, verify it through the affected application before revoking the old value, unless the old value has been compromised.

Before changing a credential

Record the responsible administrator, non-secret credential ID, expiry, affected Namespaces and Agents, and where the value is stored. Include shared accounts, Configurations, and automation clients. Keep credential values out of tickets, logs, shell history, and Configuration documents.

Verify that you have another working administrator credential before changing controller credentials. Arrange a maintenance window when a replacement needs process restarts or the upstream provider cannot overlap credentials. Record the required verification and who can stop affected workloads if access must be revoked immediately.

Choose the credential owner

Replace an OCC service API key

For routine renewal, follow issue a service key using an authorized administrator. Store the one-time value privately and retain its non-secret ID and expiry. Switch the client to the replacement, then exercise an operation the client normally performs. Verify that its permissions allow that operation and reject one outside its grants.

Only after that check, revoke the old key and verify that it returns 401. Issuing or revoking a key does not change IAM grants, revoke other keys for the principal, or cancel running Agent work. To end a human operator session, use sign-out and verify that a protected request with the old session fails.

Replace runtime values and verify consumption

Obtain replacement API keys and channel credentials through the provider's supported process. For a harness API key or Configuration channel Secret, use its supported value update instead of editing its backing object directly. Generated transport credentials are separate from channel Secrets; the current initial provisioning flow does not rotate an existing generated bundle.

List all affected applications or Agents before restarting or deploying them. A running process keeps the environment variables it received, even after the source Secret changes. For a model API key, the supported sequence is:

1. Update the existing OCC Secret through its API, retaining the Secret reference.
2. Run occ agent deploy "$AGENT_ID" for each consuming Agent, even when its Configuration and harnessAuth reference are unchanged.
3. Wait for the new revision to become active, then perform a real model request.

With Kubernetes Compute, OCE preparation refreshes the Harness's DP credential projection from the CP source. Recreating its Pod or running kubectl rollout restart reads the existing projection and is not a substitute for this OCE deployment.

For a channel credential, explicitly deploy each consumer and exercise the affected channel workflow; a successful model turn does not prove channel authentication. For transport tokens, coordinate both endpoints and clients, and verify a fresh allowed connection and rejection of the old token. No automatic coordinated transport-token rotation is provided.

Where the provider permits overlap, revoke the old upstream credential after successful replacement checks. A stored credential status does not show that the provider accepts the value. Dedicated Gateway restarts read current canonical channel values; Harness restarts read their existing runtime projection. Revision history does not restore old source values.

Backend-managed account credentials require separate handling: OCC cannot refresh, rotate, or manually replace an issued token. Monitor expiry and arrange a separately issued replacement account before it expires. Bind that account and explicitly deploy each intended consumer. Account deletion performs upstream cleanup and is blocked by Agent drafts, active revisions, and pending deployments; inactive history alone does not retain the source indefinitely.

Preserve administrator recovery

Replace the mounted auth signing Secret through the deployment owner and restart the API processes that consume it. Verify fresh human sign-in and authenticated API access; do not assume existing sessions survive. This change does not replace human passwords or runtime provider credentials.

The initial bootstrap service key expires after 30 days. Preserve authorized administrator access and renew automation credentials before expiry. Deleting a local delivery copy does not revoke its credential. An already-bootstrapped Installation will not reissue lost passwords or keys; follow key recovery and preserve uncertain bootstrap state for investigation.

For a compromised credential, prioritize containment over routine overlap: stop the affected workloads and revoke at the credential's authority. Updating or deleting a Secret alone cannot remove values from running processes. Verify rejection, provision replacements through the appropriate path above, and resume only the intended applications or Agents. To stop an Agent, use its exact stop endpoint. To permanently remove it, delete the Agent; teardown is asynchronous. IAM revocation prevents OCC from accepting or starting later operations, but it cannot retract credentials already delivered to a process.