Provider Key Rotation

Provider key rotation replaces the credential AISIX uses to reach an upstream provider. It does not require callers to change their caller API keys or model aliases.

Rotate a provider key in place when every dependent model can switch to the new credential together. Create a replacement provider key when you want to migrate models gradually and keep the old credential available for rollback.

Prerequisites

Before starting, prepare the following:

The replacement upstream credential.
An inventory of every model that uses the provider key. A provider key is a shared dependency, so changing it in place affects every dependent model.
For AISIX Cloud, permission to manage provider keys and models.
For the open-source AISIX gateway, access to the gateway process environment and the declarative resources file.
If the replacement also changes the upstream endpoint or protocol, review Provider Compatibility.

Choose a Rotation Strategy

Strategy	Effect	Use When
In-place rotation	Keeps the provider key reference and switches every dependent model together.	You can validate the replacement credential quickly and accept one coordinated transition.
Replacement provider key	Keeps both credentials available while models move to a new provider key.	You need gradual rollout, per-model verification, or a straightforward rollback path.

Rotate a Provider Key in AISIX Cloud

AISIX Cloud stores provider credentials as write-only secrets. Read operations never return the stored credential. Updating the secret on an existing provider key preserves its ID, so dependent models do not need to change.

Callers do not need new caller API keys, and applications do not need to change model aliases as long as those aliases keep the same names.

Rotate in Place

In the dashboard:

Open Provider keys and select Edit on the key.
Enter the replacement value in Upstream API key. The field is blank because the control plane does not return the stored secret; leaving it blank keeps the current value. For a provider whose credential has several fields, supply every required field and select one credential method when alternatives are available. The credential is replaced as a whole, not field by field.
Select Save. The control plane encrypts the replacement credential and projects it to every environment allowed to use the key. Resource Projection explains how saved configuration becomes active gateway configuration.
Send requests through each affected model and confirm the upstream accepts the new credential.

To automate the same operation, use an admin token with write access. The AISIX Cloud Admin API Reference defines the complete request and response schemas.

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

Send the replacement plaintext secret in api_key:

curl -sS -X PATCH "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_NEW_UPSTREAM_API_KEY"
  }'

Omitting api_key leaves the stored secret unchanged. An empty value is rejected.

For a provider whose credential has several fields, send the complete replacement credential in config. This example rotates an Amazon Bedrock credential:

curl -sS -X PATCH "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "access_key_id": "YOUR_NEW_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_NEW_SECRET_ACCESS_KEY",
      "region": "us-west-2"
    }
  }'

The whole structured credential is replaced, so include every field the provider requires. For example, Google Vertex AI requires project, region, and exactly one of access_token or service_account_json.

caution

An in-place rotation switches every dependent model to the replacement credential. If the credential is invalid, those models fail until you provide a working value. Use a replacement provider key when you need to keep the old credential available during verification.

Rotate with a Replacement Provider Key

In the dashboard:

Create a provider key with the same provider and endpoint settings as the old key, but supply the replacement credential. For a bring-your-own upstream, select the same adapter.
Allow the replacement key in every affected environment.
Edit each affected model and select the replacement provider key. The dropdown lists only provider keys allowed in that environment. If the replacement key is missing, update its allowed environments first.
After the configuration reaches the gateways, send live requests through the migrated models. See Resource Projection if a saved change has not reached a gateway.
Delete the old provider key only after every dependent model has moved and the replacement credential has been verified.

The following API example migrates models in one environment. If the old provider key is shared across environments, allow the replacement key in every affected environment and migrate all dependent models before deleting the old key. Include direct models as well as embedding models used by semantic routers.

Export the AISIX Cloud connection details and the affected resource IDs:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export MODEL_IDS="YOUR_MODEL_ID_1 YOUR_MODEL_ID_2"
export OLD_PROVIDER_KEY_ID="YOUR_OLD_PROVIDER_KEY_ID"

Create the replacement provider key and copy its returned ID:

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "provider": "openai",
  "display_name": "OpenAI replacement",
  "api_key": "YOUR_NEW_UPSTREAM_API_KEY",
  "allowed_environments": ["${ENV_ID}"]
}
EOF

For a bring-your-own upstream, include the endpoint and adapter required by that provider key type.

Export the replacement ID, then update each affected model:

export REPLACEMENT_PROVIDER_KEY_ID="YOUR_REPLACEMENT_PROVIDER_KEY_ID"

for MODEL_ID in $MODEL_IDS; do
  curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "provider_key_id": "${REPLACEMENT_PROVIDER_KEY_ID}"
}
EOF
done

After every affected model succeeds with the replacement credential, remove the old provider key:

curl -sS -X DELETE "$AISIX_CP/provider_keys/$OLD_PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

Deleting a provider key that models still reference prevents those models from dispatching successfully. Rebind every dependent model before deletion.

Rotate a Provider Key in the Open-Source AISIX Gateway

The resources file references provider keys by display_name. The gateway resolves environment variables when it loads the file, so changing a variable in your shell does not update an already-running gateway process.

Rotate in Place

Keep the provider key entry and its environment-variable name unchanged:

resources.yaml
provider_keys:
  - display_name: openai-prod
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

Replace OPENAI_API_KEY in the environment used to start the gateway, then restart or recreate the gateway so the process receives the new value. Because the provider key name stays openai-prod, no model references need to change.

Rotate with a Replacement Provider Key

Make both credentials available to the gateway process and declare both provider keys:

resources.yaml
provider_keys:
  - display_name: openai-prod
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY_OLD}
    api_base: https://api.openai.com/v1
  - display_name: openai-replacement
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY_NEW}
    api_base: https://api.openai.com/v1

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-replacement

The replacement is a separate provider key. Copy every applicable non-secret field from the old entry, including provider, adapter, api_base, strip_headers, telemetry_tags, request, and response. Change only the display_name and credential reference unless another setting is intentionally changing.

Restart or recreate the gateway if the replacement environment variable was not already available to its process. To migrate models in stages, keep both provider keys in the file, change selected model references to openai-replacement, and validate and reload the file after each cohort. Remove openai-prod only after no model references it and live requests succeed through every migrated model.

Verify the Rotation

The gateway request used to verify a model is independent of its management path. For each affected model:

Send a representative live request through its caller-facing alias with an authorized caller API key.
Use the endpoint and request shape that the model normally serves. For example, verify an embedding model through /v1/embeddings, not the chat-completions endpoint.
Confirm that the upstream accepts the replacement credential and returns the expected response.

When using a replacement provider key, confirm that every affected model references it before deleting the old key. In AISIX Cloud, use Request Logs to inspect the verification requests and Resource Projection if a saved change has not reached a gateway. For the open-source gateway, check Configuration Status after reloading the resources file.

Next Steps

You have now rotated a provider credential without changing caller-facing access. Continue with Provider Compatibility to compare supported request paths and adapter behavior before moving a model to a different upstream.

Prerequisites​

Choose a Rotation Strategy​

Rotate a Provider Key in AISIX Cloud​

Rotate in Place​

Rotate with a Replacement Provider Key​

Rotate a Provider Key in the Open-Source AISIX Gateway​

Rotate in Place​

Rotate with a Replacement Provider Key​

Verify the Rotation​

Next Steps​

Prerequisites

Choose a Rotation Strategy

Rotate a Provider Key in AISIX Cloud

Rotate in Place

Rotate with a Replacement Provider Key

Rotate a Provider Key in the Open-Source AISIX Gateway

Rotate in Place

Rotate with a Replacement Provider Key

Verify the Rotation

Next Steps