Provider Keys

Create a provider key to store the upstream credential and endpoint settings AISIX uses after resolving a model alias. In AISIX Cloud, models reference provider keys by ID. For the open-source AISIX gateway, models in resources.yaml reference them by display_name. Both paths keep upstream credentials out of application code and allow one credential to be reused across multiple aliases.

The resource lifecycle examples use the AISIX Cloud Admin API. The field and behavior sections also explain the equivalent resources.yaml configuration for the open-source AISIX gateway.

Prerequisites

Before starting, prepare the following:

Access to AISIX Cloud with an environment and an admin token that has write scope. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
An upstream provider credential.

Set the shared variables used by the examples on this page:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a Provider Key

First, create the provider key and save its returned ID for a model configuration.

Provider keys are organization-scoped. allowed_environments lists the environments that may reference the key when creating models, so include the environment where the models will live.

The example below uses OpenAI as the upstream provider:

# Replace with your value
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-prod",
    "provider": "openai",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

You should see a response similar to the following:

{
  "provider_key": {
    "id": "db8613ea-2ecd-40e4-91aa-08197119f766",
    "org_id": "3f1c2b6a-9d4e-4c1f-8a2b-5e6d7c8f9a0b",
    "provider": "openai",
    "display_name": "openai-prod",
    "allowed_environments": ["9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"],
    "strip_headers": null,
    "telemetry_label": "openai-prod",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  }
}

The create response does not include api_base; fetch the key with GET $AISIX_CP/provider_keys/{id} to see the endpoint override.

Copy the highlighted id and export it. You will use it as provider_key_id when creating models:

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

This creates the upstream credential resource only. To send traffic through AISIX, attach the provider key to a model, allow that model on a caller API key, and send a proxy request with the caller API key.

Set Provider and Adapter

Provider keys separate the upstream identity from the upstream API format.

In AISIX Cloud, a provider identifies the upstream vendor or endpoint. It is not an open string: provider must be either an AISIX provider-catalog ID, such as openai, anthropic, or deepseek, or the sentinel value byo for a bring-your-own endpoint. The catalog includes native AISIX integrations and community entries sourced from models.dev. For the open-source AISIX gateway, provider in resources.yaml is an open label and adapter selects the implemented protocol family.

An adapter identifies the upstream API format AISIX should use. It is a closed value because AISIX can only encode implemented protocol families, such as openai, anthropic, bedrock, vertex, and azure-openai.

For an AISIX Cloud catalog provider, the control plane derives the adapter from the catalog entry; sending an adapter field returns a 400 error. The OpenAI example above sets only provider: "openai", and the control plane derives the OpenAI adapter. A catalog provider that exposes an OpenAI-compatible API, such as DeepSeek, works the same way — set provider and, when needed, api_base:

{
  "provider": "deepseek",
  "api_base": "https://api.deepseek.com"
}

For a private or OpenAI-compatible endpoint that is not in the AISIX Cloud catalog, set provider to byo, choose the adapter explicitly, and configure api_base, which is required for BYO keys:

{
  "provider": "byo",
  "adapter": "openai",
  "api_base": "https://api.example.com/v1"
}

The AISIX Cloud Admin API does not allow changing the adapter of an existing BYO provider key. Create a new provider key with the required adapter and update dependent models to reference it. For the open-source AISIX gateway, change the adapter in the provider key entry in resources.yaml and reload the configuration.

For adapter selection details, see Adapter Protocol Families.

Configure the Base URL

api_base controls where AISIX sends upstream requests. Configure it in the shape expected by the selected adapter. AISIX Cloud can supply a catalog default when one is available, while the open-source gateway derives an endpoint only for the provider-specific cases identified in the setup guides.

Common examples are:

Upstream API	Adapter	Base URL
OpenAI	`openai`	`https://api.openai.com/v1`
DeepSeek	`openai`	`https://api.deepseek.com`
Gemini OpenAI-compatible API	`openai`	`https://generativelanguage.googleapis.com/v1beta/openai`
Anthropic	`anthropic`	`https://api.anthropic.com`
Azure OpenAI	`azure-openai`	`https://<resource>.openai.azure.com`
AWS Bedrock	`bedrock`	`https://bedrock-runtime.<region>.amazonaws.com`
Google Vertex AI	`vertex`	`https://<region>-aiplatform.googleapis.com`

For Bedrock, the AISIX Cloud Admin API requires the regional runtime endpoint as api_base. The open-source AISIX gateway can omit it for standard AWS and let the AWS SDK derive the endpoint from region.

AISIX normalizes common copy-paste mistakes, such as trailing slashes and full endpoint paths. It does not guess arbitrary provider URL layouts. For private model services, corporate proxies, or bring-your-own endpoints, configure api_base explicitly.

Credential Handling

Provider keys store sensitive upstream credentials. Assign ownership for the upstream credential before reusing one provider key across multiple models.

In AISIX Cloud, api_key is write-only. The plaintext value is encrypted before storage and is never returned by read endpoints. Bedrock and Vertex AI use a structured config object because their credentials have multiple fields. When creating these provider keys, set the required api_key field to an empty string and supply the credential through config. When updating config, omit api_key; update requests reject an empty api_key.

For the open-source AISIX gateway, reference credentials in resources.yaml through environment variables instead of storing literal secrets in YAML. Structured credentials are JSON values supplied through the provider key's api_key field.

Provider keys are shared dependencies. Rotating one provider key affects every model that references it. In AISIX Cloud, use Provider Key Rotation to choose between an in-place update and a gradual replacement workflow. For the open-source gateway, update the credential supplied to the provider key and restart the gateway with the new environment value. Verify either change with live gateway traffic.

Configure Provider-Specific Overrides

Provider-key overrides adapt an upstream API that differs slightly from the selected adapter. Every model that references the provider key inherits its overrides, so configure them only when needed.

The following example configures request and response compatibility for a custom OpenAI-compatible upstream:

export COMPAT_API_KEY="YOUR_UPSTREAM_API_KEY"

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "custom-openai-prod",
    "provider": "byo",
    "adapter": "openai",
    "api_key": "'"${COMPAT_API_KEY}"'",
    "api_base": "https://api.example.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"],
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    },
    "response": {
      "reasoning_field": "delta.thinking"
    }
  }'

❶ request.param_renames renames a top-level parameter when an upstream expects a different name. If a request contains both names, AISIX uses the value from the original caller-facing name.

❷ response.reasoning_field maps reasoning from a nonstandard streaming delta path to delta.reasoning_content. This override applies to the openai and azure-openai adapters.

Support varies by adapter and request path. The request and response override objects accept the same fields on the AISIX Cloud Admin API provider-key resource and in a declarative resources.yaml provider key entry; see the Resources File Reference for the field catalog.

The request object also controls the headers AISIX sends upstream: request.default_headers injects headers that can carry request context such as the calling team, and request.forward_client_headers relays selected caller headers. See Upstream Request Headers.

Verify the Provider Key

Send a representative request through a model that uses the provider key and confirm that the upstream accepts it. If you configured a custom reasoning_field, send a streaming chat-completions request and confirm that reasoning appears in delta.reasoning_content.

Test provider-key overrides with a non-production alias before reusing the key across models. An incorrect override affects every model that references the provider key.

Next Steps

Continue with Model Aliases to attach the provider key to a caller-facing alias.

Prerequisites​

Create a Provider Key​

Set Provider and Adapter​

Configure the Base URL​

Credential Handling​

Configure Provider-Specific Overrides​

Verify the Provider Key​

Next Steps​