Merge pull request #134 from Portkey-AI/openapi-spec/4432-admin-api-upgrade

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

Author: sk-portkey

openapi.yaml

@@ -17686,6 +17686,19 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/UpdateApiKeyObject"
+            examples:
+              update_api_key:
+                summary: Update key metadata and limits
+                value:
+                  name: API_KEY_NAME_0909
+                  rate_limits:
+                    - type: requests
+                      unit: rpm
+                      value: 100
+              reset_usage:
+                summary: Reset accumulated usage for this key
+                value:
+                  reset_usage: true
       parameters:
         - name: id
           in: path
@@ -17821,7 +17834,7 @@ paths:
         - lang: curl
           label: Default
           source: |
-            curl -X GET "https://api.portkey.ai/v1/api-keys/{id}"
+            curl -X PUT "https://api.portkey.ai/v1/api-keys/{id}" \
               -H "x-portkey-api-key: PORTKEY_API_KEY" \
               -H "Content-Type: application/json" \
               -d '{
@@ -17885,7 +17898,7 @@ paths:
         - lang: curl
           label: Self-Hosted
           source: |
-            curl -X GET "SELF_HOSTED_CONTROL_PLANE_URL/api-keys/{id}" \
+            curl -X PUT "SELF_HOSTED_CONTROL_PLANE_URL/api-keys/{id}" \
             -H "x-portkey-api-key: PORTKEY_API_KEY" \
             -H "Content-Type: application/json" \
             -d '{
@@ -18253,6 +18266,130 @@ paths:
             })
             console.log(apiKey);
 
+  /api-keys/{id}/rotate:
+    servers: *ControlPlaneServers
+    post:
+      tags:
+        - Api-Keys
+      summary: Rotate API Key
+      description: |
+        Rotates an existing API key and returns a newly generated key value.
+        The previous key remains valid during the transition period and expires at `key_transition_expires_at`.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RotateApiKeyRequest"
+            examples:
+              default:
+                summary: Rotate with a custom transition period
+                value:
+                  key_transition_period_ms: 3600000
+      parameters:
+        - name: id
+          in: path
+          schema:
+            type: string
+            format: uuid
+          required: true
+      responses:
+        "200":
+          description: OK
+          headers:
+            Content-Type:
+              schema:
+                type: string
+                example: application/json
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RotateApiKeyResponse"
+      x-code-samples:
+        - lang: python
+          label: Default
+          source: |
+            import requests
+
+            response = requests.post(
+                "https://api.portkey.ai/v1/api-keys/API_KEY_ID/rotate",
+                headers={
+                    "x-portkey-api-key": "PORTKEY_API_KEY",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "key_transition_period_ms": 3600000
+                }
+            )
+
+            print(response.json())
+        - lang: javascript
+          label: Default
+          source: |
+            const response = await fetch("https://api.portkey.ai/v1/api-keys/API_KEY_ID/rotate", {
+              method: "POST",
+              headers: {
+                "x-portkey-api-key": "PORTKEY_API_KEY",
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                key_transition_period_ms: 3600000
+              }),
+            });
+
+            const rotatedApiKey = await response.json();
+            console.log(rotatedApiKey);
+        - lang: curl
+          label: Default
+          source: |
+            curl -X POST "https://api.portkey.ai/v1/api-keys/{id}/rotate" \
+              -H "x-portkey-api-key: PORTKEY_API_KEY" \
+              -H "Content-Type: application/json" \
+              -d '{
+                "key_transition_period_ms": 3600000
+              }'
+        - lang: python
+          label: Self-Hosted
+          source: |
+            import requests
+
+            response = requests.post(
+                "SELF_HOSTED_CONTROL_PLANE_URL/api-keys/API_KEY_ID/rotate",
+                headers={
+                    "x-portkey-api-key": "PORTKEY_API_KEY",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "key_transition_period_ms": 3600000
+                }
+            )
+
+            print(response.json())
+        - lang: javascript
+          label: Self-Hosted
+          source: |
+            const response = await fetch("SELF_HOSTED_CONTROL_PLANE_URL/api-keys/API_KEY_ID/rotate", {
+              method: "POST",
+              headers: {
+                "x-portkey-api-key": "PORTKEY_API_KEY",
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                key_transition_period_ms: 3600000
+              }),
+            });
+
+            const rotatedApiKey = await response.json();
+            console.log(rotatedApiKey);
+        - lang: curl
+          label: Self-Hosted
+          source: |
+            curl -X POST "SELF_HOSTED_CONTROL_PLANE_URL/api-keys/{id}/rotate" \
+              -H "x-portkey-api-key: PORTKEY_API_KEY" \
+              -H "Content-Type: application/json" \
+              -d '{
+                "key_transition_period_ms": 3600000
+              }'
+
   /policies/usage-limits:
     post:
       tags:
@@ -34306,6 +34443,10 @@ components:
                 example: 100
         usage_limits:
           $ref: "#/components/schemas/UsageLimits"
+        reset_usage:
+          type: boolean
+          description: Whether to reset current usage. If the current status is exhausted, this will change it back to active.
+          example: true
         scopes:
           type: array
           items:
@@ -34330,6 +34471,32 @@ components:
             format: email
             example: "foo@bar.com"
 
+    RotateApiKeyRequest:
+      type: object
+      properties:
+        key_transition_period_ms:
+          type: integer
+          minimum: 1800000
+          description: Optional transition period in milliseconds during which the previous key remains valid.
+          example: 3600000
+
+    RotateApiKeyResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          example: "550e8400-e29b-41d4-a716-446655440000"
+        key:
+          type: string
+          description: Newly rotated API key value.
+          example: "pk_live_new_rotated_key_value"
+        key_transition_expires_at:
+          type: string
+          format: date-time
+          description: Timestamp when the previous key version stops being accepted.
+          example: "2026-01-15T10:30:00.000Z"
+
     PromptRenderResponse:
       type: object
       required: