Provider Key Rotation

Provider key rotation replaces an upstream credential while keeping caller-facing API keys and model aliases stable. Callers keep sending the same model values with the same caller API keys, and only the upstream credential AISIX uses to reach the provider changes.

Rotate a provider key in place when the upstream provider issues you a replacement secret. Every model that references the key picks up the new credential, so there is nothing to change on the models or on the caller side.

Rotate by creating a replacement key instead when you want to move models over one at a time and keep the old credential available to fall back on.

Before You Begin

• You are an owner or member who can manage provider keys in the target environment.
• You have the new upstream secret (for example, a freshly issued provider API key).
• You know which models reference the provider key you are rotating. A provider key is a shared dependency, so an in-place rotation affects every model that references it at once.

How Rotation Works

The control plane stores provider-key secrets as write-only credential material. It never returns a stored secret, so rotation supplies a new value without revealing the existing one.

Models reference a provider key by ID and resolve its credential at request time. Replacing the secret on the key therefore reaches every dependent model without updating any of them.

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 a Provider Key in Place

In the Dashboard

1. Open Provider keys and select Edit on the key you are rotating.
2. Enter the new secret in Upstream API key. The field is blank because the control plane does not return the stored secret, and leaving it blank keeps the current key. For a provider whose credential has several fields, such as Amazon Bedrock or Google Vertex AI, fill in all required fields and select one credential method when alternatives are available. The credential is replaced as a whole, not field by field.
3. Select Save. The control plane re-encrypts the credential and projects it to every environment the key is allowed in. Resource Projection explains how saved configuration becomes active gateway configuration.
4. Send requests for the affected models through the managed gateway endpoint and confirm they succeed on the new credential. See Verify Rotation.

Use the API

Use the API when rotation is part of automation. Authenticate with an admin token that has write scope. For exact request and response schemas, see the Cloud Admin API Reference.

Set the values used by the examples:

# Replace with your values
export AISIX_CP_API="https://<your-cp-api-host>/api"
export AISIX_ADMIN_TOKEN="YOUR_ADMIN_TOKEN"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

Send the new secret in api_key:

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

Omitting api_key leaves the stored secret untouched, so a request that updates other fields does not need to resend the credential. An empty api_key is rejected rather than treated as clearing the key.

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

curl -sS -X PATCH "${AISIX_CP_API}/provider_keys/${PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_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"
    }
  }'

Include every field the provider requires, not only the ones that changed. 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 model on the key at once. If the new credential is wrong, the affected models fail until you send a working credential. To keep a fallback available while you verify, use a replacement key instead.

Rotate Gradually with a Replacement Key

Rotate this way when you want to move models to the new credential one at a time, verify each, and keep the old credential in place to switch back to. It is the safer choice for a provider key many models depend on.

Create the replacement key, update each affected model, confirm live traffic, and only then remove the old key.

In the Dashboard

1. Open Provider keys, select New provider key, and enter the same provider and base URL as the key you are replacing. Use the new upstream secret. For a bring-your-own upstream, re-select the same protocol adapter. Catalog providers set the adapter automatically. Allow the key in the environment whose models you are rotating, then select Create provider key.
2. Open Models in that environment, select Edit on each affected model, and change the Provider key dropdown to the replacement key. The dropdown lists only keys eligible in this environment. If the replacement key is missing, widen its allowed environments on the Provider keys page first. Then save each model.
3. Wait for the control plane to project the updated models to the managed gateway. Resource Projection explains how saved configuration becomes active gateway configuration.
4. Send requests for the affected models through the managed gateway endpoint and confirm they succeed on the new credential. See Verify Rotation.
5. Only after live traffic is confirmed, delete the old provider key. Deleting a key that models still reference breaks those models, so update every dependent model first.

Use the API

The example below rotates models in one environment. If the old provider key is shared across multiple environments, create the replacement key with all affected environments allowed. Then update every affected model in each environment before deleting the old key.

Set MODEL_IDS to the model resources in ENV_ID that currently reference the old provider key, including embedding models used by semantic routers. Use one model ID for a single-model rotation, or a space-separated list when the provider key is shared within that environment.

Set the values used by the examples:

# Replace with your values
export AISIX_CP_API="https://<your-cp-api-host>/api"
export AISIX_ADMIN_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 the returned provider key ID:

curl -sS -X POST "${AISIX_CP_API}/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "OpenAI replacement",
    "api_key": "YOUR_NEW_UPSTREAM_API_KEY",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

For a bring-your-own upstream, include the endpoint and adapter fields required by your provider key type. The Cloud Admin API Reference lists the full provider key schema.

Set the replacement provider key ID from the create response:

# Replace with your values
export REPLACEMENT_PROVIDER_KEY_ID="YOUR_REPLACEMENT_PROVIDER_KEY_ID"

Update each affected model to use the replacement provider key:

for MODEL_ID in ${MODEL_IDS}; do
  curl -sS -X PATCH "${AISIX_CP_API}/environments/${ENV_ID}/models/${MODEL_ID}" \
    -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "provider_key_id": "'"${REPLACEMENT_PROVIDER_KEY_ID}"'"
    }'
done

After live traffic succeeds on the replacement credential for every affected model, delete the old provider key:

curl -sS -X DELETE "${AISIX_CP_API}/provider_keys/${OLD_PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}"

caution

Do not delete the old provider key until a live request through the managed gateway has succeeded on the replacement key. Until then, keep both keys so you can switch back to the old key if the new credential is wrong.

Verify Rotation

Verify that the new credential is serving traffic:

1. Send a request for each affected model through the managed gateway endpoint and confirm it succeeds.
2. Check Request Logs to confirm the new requests succeeded.
3. When you rotated with a replacement key, confirm on the Models page that each affected model now shows the replacement provider key, then remove the old key.

If live traffic fails, check the new upstream secret and any provider-specific authentication requirements. If a model is saved with the replacement key but the gateway still serves old behavior, check Resource Projection before assuming the new credential is invalid.

Next Steps

You have now rotated a provider credential without changing caller-facing access. Continue with Logging and Auditing to inspect live managed gateway requests after a rotation.