Provider Keys

Create a provider key to store the upstream credential and endpoint settings AISIX uses after resolving a model alias. Models reference provider keys by ID, so upstream credentials stay out of application code and can be reused across multiple aliases.

Prerequisites

Before starting, prepare the following:

• A self-hosted gateway with the admin listener available.
• The admin key from the gateway config.yaml.
• An upstream provider credential.

Create a Provider Key

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

The example below uses OpenAI as the upstream provider:

# Replace with your values
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "display_name": "openai-prod",
    "provider": "openai",
    "adapter": "openai",
    "secret": "${OPENAI_API_KEY}",
    "api_base": "https://api.openai.com/v1"
  }
EOF

You should see a response similar to the following:

{
  "id": "db8613ea-2ecd-40e4-91aa-08197119f766",
  "value": {
    "display_name": "openai-prod",
    "secret": "***",
    "api_base": "https://api.openai.com/v1",
    "provider": "openai",
    "adapter": "openai",
    "telemetry_tags": {
      "featured": false
    },
    "strip_headers": [
      "authorization",
      "cookie",
      "set-cookie",
      "x-api-key"
    ]
  },
  "revision": 1
}

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

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.

A provider identifies the upstream vendor or endpoint. It is an open string, such as openai, deepseek, openrouter, or the name of a private endpoint.

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.

Use both fields together. The OpenAI example above uses provider: "openai" and adapter: "openai" because the upstream vendor and API format are both OpenAI.

For a non-OpenAI vendor that exposes an OpenAI-compatible API, keep the vendor name in provider and use the OpenAI adapter:

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

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; do not rely on AISIX to infer a default provider URL.

Common examples are:

Upstream	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	Leave unset for standard AWS; set only for a private Bedrock endpoint
Google Vertex AI	vertex	https://<region>-aiplatform.googleapis.com

AISIX normalizes common copy-paste mistakes, such as trailing slashes and full endpoint paths. It does not guess arbitrary provider URL layouts. For private gateways, 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 self-hosted deployments, the gateway stores secret as plaintext under the configured etcd prefix. Anyone with read access to that etcd keyspace can read the credential, so restrict etcd network access, use encryption at rest where available, and keep the gateway-to-etcd channel inside trusted infrastructure.

Provider keys are shared dependencies. Rotating one provider key affects every model that references it.

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 "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "display_name": "custom-openai-prod",
    "provider": "custom-openai",
    "adapter": "openai",
    "secret": "${COMPAT_API_KEY}",
    "api_base": "https://api.example.com/v1",
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    },
    "response": {
      "reasoning_field": "delta.thinking"
    }
  }
EOF

❶ 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. For all available request and response fields and their accepted values, see Provider Keys in the Admin API Reference.

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.