Skip to main content
This guide lists every credential that Portkey stores or issues for an organisation, and how to rotate each one. Work through the sections in order.
Portkey does not support grace periods when you replace credentials stored in integrations, providers, MCP servers, or other settings. Saving a new value does not take effect on every gateway at once. Hybrid and self-hosted gateways clear cached keys, integrations, and configs on a sync that runs about once a minute, and values read from a vault are cached for up to 5 minutes. For each credential: create the new value at the source, update Portkey, wait for the change to propagate, confirm requests succeed with the new value on every gateway, then revoke the old value at the source.

​
Credentials at a glance

​
Before you start

  • Use a rotation account you trust. Sign in to the Portkey dashboard with SSO or your own credentials. Don’t depend on an existing API key to run the rotation.
  • Plan for downtime. Replacing a credential breaks any application still using the old value. Roll out new values to your applications before revoking the old ones.
  • Keep a list. Record each credential you rotate, so you can confirm none was missed. Use the checklist at the end of this page.
  • Know your permissions. Rotating organisation-level resources requires an organisation owner or admin. Workspace-level resources require a workspace admin or manager.

​
1. Portkey API keys

Portkey issues three kinds of API keys. See API Keys (AuthN and AuthZ) for how they differ.
  • Admin API keys: organisation-level keys with access across workspaces
  • Workspace service API keys: workspace-level keys for backends and automation
  • Workspace user API keys: workspace-level keys owned by individual users

​
Choose a rotation method

The rotate endpoint always keeps the previous secret valid for the transition period, with a minimum of 30 minutes. To end access as soon as possible, create a new key and delete the old one. Gateways cache API keys and clear changed ones on a sync that runs about once a minute, so confirm the old key returns 401 on every gateway, including self-hosted ones, before treating it as revoked.

​
Rotate with the dashboard

1

Open API Keys

Go to API Keys.
2

Create a replacement key

Click Create. Select the same type, workspace, scopes, and rate or budget limits as the key it replaces. Also copy its default config and its Config Override setting. Without them the new key loses the routing and guardrails attached to the old one, or lets requests override the config.
3

Deploy the new key

Update your applications, CI pipelines, secret stores, and x-portkey-api-key headers with the new key.
4

Delete the old key

After traffic moves to the new key, delete the old key from the list.

​
Rotate with the API

  1. Create an API key with POST /v2/api-keys/{sub-type}. Set the same default config and config-override setting as the old key.
  2. Deploy the new key.
  3. Delete the old key with DELETE /v2/api-keys/{id}.
To keep the same key ID instead, call POST /v2/api-keys/{id}/rotate. The response contains the new secret and the time the previous secret expires.

​
Order of rotation

  1. Rotate admin API keys first. They can create or modify every other resource.
  2. Rotate workspace service API keys next. They can manage other workspace keys.
  3. Rotate workspace user API keys last. Ask each user to replace theirs, or rotate them as an admin.
List existing keys with GET /v2/api-keys to find every key to replace. Delete any key you don’t recognise or no longer use.

​
2. AI provider credentials

Integrations, providers, and virtual keys hold credentials for your AI providers: API keys, cloud access keys, service account JSON, and similar. Rotating the key only in Portkey does not invalidate the old one. Rotate the credential at the provider. For each integration:
1

Create a new credential at the provider

Generate a new API key, access key, or service account key in your provider’s console.
2

Update the credential in Portkey

In the dashboard, open Model Catalog, select the integration, and replace the stored credential. To use the API, call PUT /integrations/{slug} or PUT /providers/{slug}.
3

Test a request

Send a test request through a model on the integration to confirm the new credential works.
4

Revoke the old credential at the provider

Delete or disable the old key in your provider’s console.

​
Credentials by provider

Integrations that use workload identity federation do not store a static provider key, but they do use an identity provider client secret. Create a replacement client secret at the IdP, update it in the integration (or the vault entry it references), send a test request, then revoke the old secret. Also review the trust relationship and allowed subjects on the cloud side.

​
Virtual keys (deprecated)

Existing virtual keys hold provider credentials too. Rotate them the same way using the dashboard or PUT /virtual-keys/{slug}. Alternatively, migrate to integrations and providers and delete the virtual key.

​
Credentials used in requests

If your applications send provider credentials per request, such as an Authorization header or x-portkey-* provider headers, rotate those in your application secret stores as well.

​
3. MCP credentials

MCP integrations and servers store credentials that Portkey uses to reach upstream MCP servers. Rotate each one at the source, then update Portkey. Also rotate any tokens the MCP server itself holds for downstream systems. Those live outside Portkey. Use GET /mcp-servers and GET /mcp-integrations to list every server and integration that needs review.

​
4. Secret references and vault credentials

Secret references point to secrets in AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault. Portkey stores the reference configuration, including the auth config it uses to reach your vault. It does not store the secret value itself. Rotate in this order:
  1. Vault access credentials. Rotate the credentials in each secret reference’s auth_config (for example an IAM access key, an Azure client secret, or a HashiCorp Vault token or AppRole secret). Update the reference with PUT /v1/secret-references/{id}. Updates to auth_config are merged, so send only the changed fields.
  2. The secrets themselves. Rotate the secret values in your vault. Gateways cache fetched values for 5 minutes, so the new value takes effect within that window with no change in Portkey.
  3. Revoke the old vault credentials.

​
5. JWT, sessions, and users

Portkey validates JWTs using your IdP’s public keys, which are not secret. Rotate signing keys at your IdP if you suspect they were exposed, and confirm the JWKS configuration in Portkey is current. See JWT.
Ask users to sign out and back in. Review organisation users and pending invites, and remove any user or invite you don’t recognise.

​
6. Credentials embedded in configs, guardrails, and prompts

Credentials sometimes end up inside saved resources instead of integrations. Review each of the following for static secrets:
  • Configs: provider keys, Authorization headers, or custom headers inside targets or override_params
  • Guardrails: API keys or headers for third-party guardrail providers, and webhook URLs, headers, or signing secrets for custom guardrails
  • Prompts and prompt partials: pasted API keys or tokens in the template text
  • Custom hosts and custom headers: bearer tokens for private endpoints
For each secret found, rotate it at the upstream service, update the saved resource, and revoke the old value. Prefer secret references over inline values so future rotation happens in your vault.

​
7. Observability and log export credentials

Rotate any credential Portkey uses to write to your systems:
  • OpenTelemetry exports: authentication headers or tokens for your OTel collector. See OpenTelemetry.
  • Log storage for self-hosted gateways: object storage access keys, HMAC secrets, or service account keys.
  • Third-party observability integrations that you configured with a token.
Create the new credential at the destination, update the Portkey configuration, confirm data is arriving, then revoke the old credential.

​
8. Self-hosted gateway secrets

For hybrid deployments, rotate every secret in your deployment configuration:
  • PORTKEY_CLIENT_AUTH: the credential your gateway uses to sync with the Portkey control plane. Contact Portkey support to have it reissued, then update your deployment and restart the gateway.
  • Log store credentials: for example LOG_STORE_ACCESS_KEY and LOG_STORE_SECRET_KEY (S3, GCS HMAC, or Azure storage).
  • Cache and database credentials: Redis, and any database your deployment uses.
  • Provider keys and other values in your environment files, Helm values, or Kubernetes secrets.
  • Test keys: replace the PORTKEY_API_KEY and OPENAI_API_KEY values from any smoke-test scripts.
Redeploy the gateway after updating secrets and confirm it registers and serves requests.

​
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.
  2. Test end-to-end. Send a request through every integration, MCP server, and key path your applications use.
  3. Review audit logs. Check audit logs under Admin Settings > Audit Logs, or call GET /audit-logs, for unexpected creation of API keys, integrations, users, or configuration changes.
  4. Review request logs and provider usage. Check logs and your AI providers’ usage dashboards for requests you didn’t make.
  5. Review users and workspaces. Remove any user, workspace member, or workspace you don’t recognise.

​
Rotation checklist

Copy this list to track progress.
  • Admin API keys replaced; old keys deleted
  • Workspace service API keys replaced; old keys deleted
  • Workspace user API keys replaced; old keys deleted
  • Application secret stores updated with new Portkey keys
  • Every integration and provider credential rotated at the provider, updated in Portkey, and old credentials revoked
  • Virtual key credentials rotated, or virtual keys migrated and deleted
  • MCP integration and server credentials rotated; user connections reset where needed
  • Secret reference vault credentials rotated; secret values rotated
  • Configs, guardrails, prompts, and custom hosts reviewed for embedded secrets
  • OTel and log export credentials rotated
  • Self-hosted gateway secrets rotated; gateway redeployed
  • Old Portkey API keys confirmed to return 401
  • Audit logs and provider usage reviewed

API Key Rotation

API Keys (AuthN and AuthZ)

Secret References

Audit Logs

Portkey is now PRISMA AIRS AI Gateway. See it in action.

Contact Us
Last modified on November 12, 2026