docs(openapi): add API key rotate endpoint and document reset_usage update flow

[akhilmmenon]

Summary

• Add OpenAPI documentation for POST /api-keys/{id}/rotate.
• Define rotate request/response schemas:
  • RotateApiKeyRequest (key_transition_period_ms)
  • RotateApiKeyResponse (id, key, key_transition_expires_at)
• Add code samples for rotate (curl, python, javascript; cloud + self-hosted).
• Keep and validate reset_usage documentation on PUT /api-keys/{id} (schema + request examples), including minimal {"reset_usage": true} usage.

Why

API key rotation is implemented in backend routes but was not available in OpenAPI docs. This PR makes the rotate endpoint discoverable and testable in the API reference, while preserving the already-documented reset_usage update flow.

Scope

• Repo: Portkey-AI/openapi
• Branch: openapi-spec/4432-admin-api-upgrade
• File changed: openapi.yaml

Test Plan

• Open OpenAPI reference and verify POST /api-keys/{id}/rotate is present.
• Confirm rotate request schema includes optional key_transition_period_ms with minimum 1800000.
• Confirm rotate success response includes id, key, and key_transition_expires_at.
• Confirm rotate code samples render for curl/python/javascript (default + self-hosted).
• Confirm PUT /api-keys/{id} still includes reset_usage in schema/examples.

Merge Timing

Keep this PR open and merge after the rotate endpoint is Generally Available.

Related

• Companion docs-core changes are in branch: docs-update/4432-admin-api-upgrade

[Copilot]

Pull request overview

Adds OpenAPI documentation so API key rotation is discoverable in the API reference, while improving/validating the existing reset_usage update flow documentation.

Changes:

• Adds POST /api-keys/{id}/rotate with request/response schemas and code samples (default + self-hosted).
• Adds explicit request examples for PUT /api-keys/{id}, including a minimal {"reset_usage": true} example.
• Extends UpdateApiKeyObject to include reset_usage and fixes the curl method for the update endpoint samples (GET → PUT).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new POST /api-keys/{id}/rotate operation does not define an operationId and is not added to the x-code-samples.groups navigation list. Since this spec’s header note says new endpoints must also be added to the groups section (see openapi.yaml:139-141), this endpoint may not show up in the rendered API reference navigation.

Suggestion: add a stable operationId (e.g., rotateApiKey) and include it under the appropriate group/section in x-code-samples.groups so it becomes discoverable in the docs UI.