docs: add credential and API key rotation guide by roh26it · Pull Request #1167 · Portkey-AI/docs-core

roh26it · 2026-11-11T04:05:21Z

Summary

Adds a step-by-step page on rotating every credential stored in or issued by the gateway: API keys, provider credentials (integrations/providers/virtual keys), MCP credentials, secret references, SSO/SCIM/JWT, secrets embedded in configs/guardrails/prompts, OTel/log-export credentials, and self-hosted gateway secrets.
Mirrored to aigw/ for Prisma AIRS AI Gateway (AI Gateway naming, /aigw/ links, no app.portkey.ai links).
Both pages added to the Support nav group in docs.json.
Page is factual only and doesn't reference any incident.

Test plan

docs.json valid; aigw/scripts/check_nav_page_parity.py passes
Internal links on the root page resolve to files
Preview with mint dev (not installed locally)
Run aigw/scripts/check_prose_endpoints.py with network access

🤖 Generated with Claude Code

Adds a step-by-step page covering every credential stored in or issued by the gateway: API keys, provider credentials, MCP credentials, secret references, SSO/SCIM/JWT, embedded secrets, observability credentials and self-hosted gateway secrets. Mirrored into aigw/ for Prisma AIRS. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

mintlify · 2026-11-11T04:05:24Z

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

Project	Status	Preview	Updated
portkey-docs	🟢 Ready	View Preview	Nov 11, 2026, 4:53 PM

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

Copilot

🟡 Changes recommended

Unresolved credential-rotation guidance risks authentication failures and lost safeguards, while AIRS instructions contain incorrect authentication requirements and unsupported API endpoints.

8 open issues

What changed in this PR

Adds a credential-rotation guide to the Portkey documentation and a mirrored version for Prisma AIRS AI Gateway.

Changes:

Documents rotation procedures for API keys, provider and MCP credentials, vault access, identity settings, and self-hosted secrets.
Includes post-rotation checks and a tracking checklist.
Adds both guides to their respective Support navigation groups.

File	Description
`support/rotate-credentials.mdx`	Adds the Portkey credential-rotation guide and checklist.
`docs.json`	Registers both guides in Support navigation.
`aigw/support/rotate-credentials.mdx`	Adapts the guide with AI Gateway terminology and AIRS links.

_{Review effort: Balanced}

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

The rotation guides include unsupported AIRS operations, incorrect authentication instructions, omitted credential types, and inaccurate revocation timing, which can leave credentials unchanged or disrupt traffic.

8 open issues

5 previously missed issues

In code that hasn't changed since last review

Use the Authorization bearer header for AIRS authentication

aigw/support/rotate-credentials.mdx:61

The AIRS authentication guide and published API specification use bearer authentication in the Authorization header, not the Portkey-specific header named here. Readers using the documented AIRS request format need to replace that bearer token when deploying the new key; please name the correct header in this step.

Add private_key_jwt signing-key rotation steps

aigw/support/rotate-credentials.mdx:161

For OIDC apps using private_key_jwt, rotating a client secret leaves the actual signing credential unchanged. The linked SSO guide documents that private key set in jwks or OIDC_CLIENT_JWKS. Add steps to register replacement public keys at the identity provider, update the stored private keys, test SSO, and remove the old public keys.

Remove the unsupported Audit Logs API alternative

aigw/support/rotate-credentials.mdx:211

The AIRS specification explicitly excludes the Audit Logs API, and GET /audit-logs is absent from the published operation list. Although the console audit-log instructions can remain, this API alternative is copied from Portkey and cannot be used on AIRS. Please remove the unsupported API call.

Verify credential propagation before revoking old credentials

support/rotate-credentials.mdx:9

Hybrid gateways invalidate cached API keys and integrations through a once-per-minute sync (self-hosting/cache-behavior.mdx:44–48), so saving or deleting a credential does not take effect immediately on every gateway. Revoking the upstream credential before propagation can interrupt traffic. Qualify this warning and the immediate-revocation claims at lines 44 and 48 with propagation and verification steps; the same changes are needed in aigw/support/rotate-credentials.mdx:9,44,48.

Include IdP client-secret rotation in workload identity federation

support/rotate-credentials.mdx:121

The documented workload identity federation flow uses an IdP client secret (oauth_client_secret), so reviewing trust relationships alone leaves that credential unchanged. Include creating a replacement secret, updating the integration or vault entry, testing requests, and revoking the old secret. Apply the same correction to aigw/support/rotate-credentials.mdx:121.

_{Review effort: Balanced}

…tion Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

- Qualify revocation timing with gateway sync and cache propagation; require verification before revoking - Preserve default config and config-override when replacing an API key - Add private_key_jwt key rotation and WIF IdP client secret rotation - aigw: use Admin API service accounts for admin credentials, Authorization bearer header, correct secret-reference base/path, drop unsupported endpoints and Prompt Studio references Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

The rotation guides omit administrative and OIDC private-key credentials, include unsupported AIRS features and incorrect endpoints, and overlook hybrid-gateway propagation delays that can cause outages or leave access active.

No open issues 🎉

8 resolved since last review

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

The rotation guides contain unresolved errors in vault update sequencing, secret transition timing, replacement-account Client IDs, and key-management authentication that can disrupt requests or cause rotation checks to fail incorrectly.

4 open issues

_{Review effort: Balanced}

+### Order of rotation
+
+1. Rotate **admin API keys** first. They have the broadest scope on the inference path.
+2. Rotate **workspace service API keys** next. They can manage other workspace keys.


+Admin API calls are authorised with a short-lived token issued to a service account in Strata Cloud Manager, using the service account's Client ID and Client Secret. Rotate these as well:
+
+1. In Strata Cloud Manager, go to **System Settings > Identity & Access** and issue a new credential for each service account used with the Admin API. If you can't issue a new credential, create a replacement service account in the same tenant with the same role assignments.
+2. Update every job, pipeline, and secret store that holds the old Client Secret.


+Generate a new API key, access key, or service account key in your provider's console.
+</Step>
+<Step title="Update the credential in Portkey">
+In the dashboard, open [**Model Catalog**](https://app.portkey.ai/model-catalog/providers), select the integration, and replace the stored credential. To use the API, call [`PUT /integrations/{slug}`](/api-reference/admin-api/control-plane/integrations/update-integration) or [`PUT /providers/{slug}`](/api-reference/admin-api/control-plane/providers/update-provider).


+
+## After rotating
+
+1. **Confirm the old credentials fail.** Wait at least a few minutes for gateway sync and caches to refresh, then send a request with each old Portkey API key through every gateway, including self-hosted ones. Expect a `401`.


Copilot AI balanced review requested due to automatic review settings November 11, 2026 04:05

Copilot started reviewing on behalf of roh26it November 11, 2026 04:05

View session

mintlify Bot deployed to staging November 11, 2026 04:06

View deployment

Copilot AI reviewed Nov 11, 2026

View reviewed changes

docs: auto-rotation available on all accounts; link from rotation guide

29aa6bd

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings November 11, 2026 16:41

mintlify Bot deployed to staging November 11, 2026 16:41

View deployment

Copilot started reviewing on behalf of roh26it November 11, 2026 16:41

View session

Copilot AI reviewed Nov 11, 2026

View reviewed changes

docs: scope availability note to key rotation; drop auto-rotation sec…

e7acc3b

…tion Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings November 11, 2026 16:50

mintlify Bot deployed to staging November 11, 2026 16:50

View deployment

Copilot started reviewing on behalf of roh26it November 11, 2026 16:50

View session

mintlify Bot deployed to staging November 11, 2026 16:53

View deployment

Copilot AI reviewed Nov 11, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings November 11, 2026 16:58

Copilot started reviewing on behalf of roh26it November 11, 2026 16:58

View session

bhishmendramahala-crypto self-requested a review November 11, 2026 16:59

sk-portkey approved these changes Nov 11, 2026

View reviewed changes

vrv-panw merged commit 60e56ba into main Nov 11, 2026
4 checks passed

Copilot AI reviewed Nov 11, 2026

View reviewed changes

roh26it mentioned this pull request Nov 12, 2026

docs: remove SSO and SCIM from credential rotation guide #1169

Merged

Navigation Menu

Repository navigation

docs: add credential and API key rotation guide - #1167

docs: add credential and API key rotation guide#1167
vrv-panw merged 4 commits into
mainfrom
docs/rotate-credentials-guide

roh26it commented Nov 11, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Nov 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		## After rotating

		1. Confirm the old credentials fail. Wait at least a few minutes for gateway sync and caches to refresh, then send a request with each old Portkey API key through every gateway, including self-hosted ones. Expect a `401`.

Conversation

roh26it commented Nov 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

mintlify Bot commented Nov 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

roh26it commented Nov 11, 2026 •

edited

Loading

mintlify Bot commented Nov 11, 2026 •

edited

Loading