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 behind the affected model resources changes.

AISIX Cloud stores provider-key secrets as write-only credential material, so the upstream secret on an existing provider key cannot be edited in place from the dashboard. To change the credential, create a replacement provider key and point each affected model at it.

Before You Begin

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

How Rotation Works

Callers keep using the same model aliases. AISIX Cloud updates the provider key reference on the affected models, then projects the change to the managed gateway. No caller-side change is required.

What changes is the provider key AISIX uses when it sends requests upstream. 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. The old provider key can stay in place until live traffic confirms the replacement path.

Rotate a Provider Key

Rotate in this order so no request is served by a missing credential. Create the replacement key, update every 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 AISIX Cloud 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

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

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:

export AISIX_CLOUD_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_CLOUD_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:

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_CLOUD_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_CLOUD_API}/provider_keys/${OLD_PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}"

Do not use the provider-key PATCH endpoint to rotate the upstream secret. That endpoint can update provider-key metadata and endpoint settings, but it does not replace the write-only api_key value.

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

After updating the affected models, verify the replacement path before deleting the old provider key:

1. On the Models page, confirm each affected model now shows the replacement provider key.
2. Send a request for each affected model through the managed gateway endpoint and confirm it succeeds.
3. Check Usage Reporting or Logging and Auditing to confirm new requests are still succeeding.

Once live traffic is confirmed, remove the old provider key.

If live traffic still fails, check the new upstream secret, provider-specific authentication requirements, and the affected models' provider-key references. If the models are 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.