Mint a new API key and retire the old one
rotate_keyGet a fresh API key for the account this connection is already acting on — the answer to a key that has been lost, leaked, pasted into a chat window, or left on a machine that is not yours.
Two calls, on purpose. rotate_key({}) mints the new key and shows it once; it revokes nothing, so whatever is running on the old key keeps running. Give the new key to the person, wait until they tell you it is saved, then call rotate_key({ confirm_saved: true, revoke_key_id: "…" }) with the id from other_live_keys to kill the old one. Revoking first would take their integration down between the two calls, and revoking without asking would do it without them knowing why.
The key is shown once and cannot be recovered. Hand it over immediately and do not repeat it in any later message, summary, log or file.
Needs a key on the connection or a linked client — it cannot help somebody holding nothing. That case starts at create_account with the account's verified address, which mails a one-time code for link_account. Free, and it renders nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| confirm_saved | No | Leave this off for the first call: it mints the new key and shows it once, and revokes nothing. Set it to `true` — together with `revoke_key_id` — only after the human has told you they have saved the new key somewhere they can read it again. That second call is what kills the old key. | |
| revoke_key_id | No | The id of the key to revoke, taken from `other_live_keys` in the first call's answer. Required with `confirm_saved`. Never guess one: revoking the wrong key takes down whatever was using it. |