Skip to main content
Your agent authenticates through its linked OAuth client, so rotation means rotating that client’s credential — a signing key for private_key_jwt, or the client secret for client_secret_basic. The agent, its grants and its owner do not change. (Native agent secrets are retired; the old agent rotate-secret route returns 410 Gone.)

​
Rotate a signing key (private_key_jwt)

A client can hold more than one registered key, so you can rotate without downtime:
  1. Register the replacement public JWK for the client (POST /api/v2/oauth/clients/{client_id}/keys, or the portal). Keep the private key in your environment; never upload it.
  2. Activate it by completing the proof-of-possession challenge (.../keys/{key_id}/activate). A registered key confers nothing until it is activated.
  3. Switch the workload. Point MUDRAID_PRIVATE_KEY_PATH and MUDRAID_KEY_ID (or your prefix’s equivalents) at the new key, recreate the SDK client — the loader reads the key at construction — and verify a token exchange and a protected request.
  4. Retire the previous key (.../keys/{key_id}/retire). The last active key of a live client cannot be retired this way, so activate the replacement first.
A custom signer= owns its own key lifecycle; register and activate its public key the same way.

​
Rotate a client secret (client_secret_basic)

POST /api/v2/oauth/clients/{client_id}/rotate-secret (an organization admin action, also in the portal) mints a new secret and shows it exactly once. The previous secret keeps working for a bounded overlap window, reported as overlap_until, so you can update MUDRAID_CLIENT_SECRET and redeploy without a gap. An expired secret gets no overlap. In production, rotation re-checks the organization’s compatibility approval. Consider moving the client to private_key_jwt instead — it is the recommended production method, and the private key never leaves your environment.

​
If a credential may be compromised

Contain first, then rotate. Suspend the client so it can no longer obtain new tokens — and, where live enforcement protects your resources, contain the agent — then rotate and verify. Replacing a local key file or secret alone does not invalidate an access token already issued: a surface validating offline may accept it until it expires. Integrations using live enforcement check containment on each protected action. Restore access through the containment workflow rather than bypassing an existing hold. See Configuration and Agent identity.