Document the API key rotate endpoint

[masnwilliams]

Summary

• Rewrites the Rotate a key section of the API Keys guide to use the new POST /org/api_keys/{id}/rotate endpoint instead of the manual create-then-delete steps.
• Documents days_to_expire (new key lifetime; omit to reuse the rotated key's original lifetime) and expire_in_days (grace window before the old key expires; 0 = immediate, default 7 days).
• Adds TypeScript, Python, and Go examples mirroring the rest of the page, and updates the troubleshooting table for expire_in_days and the new-key-shorter-than-grace 400.

Notes

• Follows the API change that added the rotate endpoint (kernel/kernel #2411, merged).
• SDK method names (apiKeys.rotate / api_keys.rotate / APIKeys.Rotate) follow the Stainless rotate method; worth a quick check once the SDKs publish, in case naming differs.

Test plan

• mintlify dev and confirm the API Keys page renders with the new section and code tabs.

---

Note

Low Risk
Documentation-only changes to the API Keys guide with no runtime or credential-handling code.

Overview
The Rotate a key section now describes the rotate API instead of a manual create-then-delete flow. It explains that one call issues a replacement key, copies name and project scope, returns plaintext key once, and keeps the old key valid during a grace period.

days_to_expire and expire_in_days are documented (new key lifetime vs. old key grace window, including 0 for immediate revocation and the default 7-day window). TypeScript, Python, and Go CodeGroup examples were added, post-rotate steps were simplified, and the troubleshooting table now covers expire_in_days validation, the rotate-specific 400 when the new key would expire before the grace window ends, and 404 wording for missing keys and project-scoped rotate limits.

^{Reviewed by Cursor Bugbot for commit 972a7f7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Jun 14, 2026, 7:16 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

PRs in the kernel, infra, hypeman, and hypeship repos. kernel is a ~mono repo with many logical services underneath, ensure to focus on the implicated service for the PR

Reason: This PR only documents an existing API endpoint without making changes to any of the four monitored repos (kernel, infra, hypeman, hypeship); it appears to be documentation-only work that doesn't require deploy monitoring.

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

Risk assessment: Very Low

Evidence from the diff: this PR modifies only info/api-keys.mdx, adding documentation text, SDK examples, and troubleshooting rows for the API key rotate endpoint. It doesn't change runtime code, site configuration, navigation, infrastructure, permissions, auth behavior, or generated API schemas.

I found no existing approvals and no CODEOWNERS file in the workspace, so this is safe to approve under the provided criteria.

  

_{Sent by Cursor Automation: Assign PR reviewers}