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
401 on every gateway, including self-hosted ones, before treating it as revoked.Rotate with the dashboard
Open API Keys
Create a replacement key
Deploy the new key
x-portkey-api-key headers with the new key.Delete the old key
Rotate with the API
- Create an API key with
POST /v2/api-keys/{sub-type}. Set the same default config and config-override setting as the old key. - Deploy the new key.
- Delete the old key with
DELETE /v2/api-keys/{id}.
POST /v2/api-keys/{id}/rotate. The response contains the new secret and the time the previous secret expires.
Order of rotation
- Rotate admin API keys first. They can create or modify every other resource.
- Rotate workspace service API keys next. They can manage other workspace keys.
- Rotate workspace user API keys last. Ask each user to replace theirs, or rotate them as an admin.
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:Create a new credential at the provider
Update the credential in Portkey
PUT /integrations/{slug} or PUT /providers/{slug}.Test a request
Revoke the old credential at the provider
Credentials by provider
Rotate an external ID
The role’s trust policy checks the external ID in itssts:ExternalId condition. Changing the ID only in the integration makes AssumeRole calls fail. Rotate it in this order:
- Add the new external ID to the trust policy’s
sts:ExternalIdcondition, keeping the old one. A condition value can list more than one ID. - Update the external ID in the integration.
- Wait for the change to propagate, then send a test request through the integration.
- Remove the old external ID from the trust policy.
Virtual keys (deprecated)
Existing virtual keys hold provider credentials too. Rotate them the same way using the dashboard orPUT /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 anAuthorization 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.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:- 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 withPUT /v1/secret-references/{id}. Updates toauth_configare merged, so send only the changed fields. - 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.
- Revoke the old vault credentials.
5. JWT, sessions, and users
JWT authentication
JWT authentication
Active sessions and users
Active sessions and users
6. Plugin integration credentials
Plugin integrations store credentials for third-party guardrail and tool providers. Rotate the credential at the provider, then update it in Portkey.Create a new credential at the plugin provider
Update the plugin integration
Update workspace override credentials
Test
Revoke the old credential at the plugin provider
credentials object inline. Review those under section 7 as well.
7. 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,
Authorizationheaders, or custom headers inside targets oroverride_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
8. 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.
9. 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. See Rotate the gateway client auth key.- Log store credentials: for example
LOG_STORE_ACCESS_KEYandLOG_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_KEYandOPENAI_API_KEYvalues from any smoke-test scripts.
Rotate the gateway client auth key
Open the gateway deployment

Rotate the key

Copy the new key

Update every deployed gateway and Data Service
PORTKEY_CLIENT_AUTH to the new key for every gateway and optional Data Service instance that uses this deployment. If your deployment references a secret store, update the underlying credential while preserving secret references and any other fields in the secret. Restart all consuming services so they load the new key before the grace period ends. Services still using the old key lose control-plane authentication once it expires.After rotating
- 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. - Test end-to-end. Send a request through every integration, MCP server, and key path your applications use.
- 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. - Review request logs and provider usage. Check logs and your AI providers’ usage dashboards for requests you didn’t make.
- 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
- Plugin integration credentials rotated, including workspace override credentials
- 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

