Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sk-portkey merged 2 commits into from
Apr 7, 2026
Merged

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
438d921
Added update_api_key example for api-keys endpoint
Apr 3, 2026
0422d00
Added openapi spec for API Key Rotation
Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 169 additions & 2 deletions openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17479,6 +17479,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
Expand Down Expand Up @@ -17614,7 +17627,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 '{
Expand Down Expand Up @@ -17678,7 +17691,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 '{
Expand Down Expand Up @@ -18046,6 +18059,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`.
Comment on lines +18062 to +18070
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
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:
Expand Down Expand Up @@ -33857,6 +33994,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:
Expand All @@ -33881,6 +34022,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:
Expand Down
Loading