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 creation examples cover both management paths. The field and behavior sections explain differences between the AISIX Cloud Admin API and the declarative resources file where they matter.

Prerequisites

Before starting, prepare the following:

• An upstream provider credential.
• For AISIX Cloud, access to an environment and an admin token with write scope. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
• For the open-source AISIX gateway, a gateway that loads a declarative resources file. The Open-Source AISIX Gateway Quickstart provides a working configuration and reload workflow.

Create a Provider Key

Configure the credential using the management path for your deployment.

AISIX Cloud

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.

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 ENV_ID="YOUR_ENVIRONMENT_ID"

The following example creates an OpenAI provider key:

# 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": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

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.

Open-Source AISIX Gateway

Add the provider key to the provider_keys collection in your resources file. Supply the credential through an environment variable instead of writing the plaintext secret into YAML:

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

Reference that variable in the provider key entry:

resources.yaml

_format_version: "1"

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

Models reference this key by its display_name, openai-prod. Validate the complete resources file before applying it. If OPENAI_API_KEY was already available to the running gateway process, follow Reload a Resources File. If you introduced the variable now, adapt the Open-Source AISIX Gateway Quickstart startup command to pass it with -e, then recreate the gateway so the process can resolve it.

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 serialized as JSON strings and supplied through the provider key's api_key field.

Provider keys are shared dependencies. Rotating one in place affects every model that references it. Use Provider Key Rotation to choose between an in-place update and a gradual replacement workflow for either management path.

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 AISIX Cloud Admin API 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.

For the open-source AISIX gateway, add the same request and response blocks to the provider key entry in the resources file.

Support varies by adapter, request path, and management path. The AISIX Cloud Admin API Reference defines the overrides accepted by the control plane. The Resources File Reference defines the complete open-source field catalog.

The request object can also control the headers AISIX sends upstream. Both management paths support request.default_headers for generated values such as the calling team and request.forward_client_headers for relaying 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 a new provider key to a caller-facing alias. To replace a credential used by existing models, follow Provider Key Rotation.