Provider Keys

In this guide, you will create a provider key and learn how its provider, adapter, and base URL settings control the upstream connection.

A provider key stores the upstream credential and endpoint settings AISIX uses after it resolves 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:

export AISIX_ADMIN_KEY="admin-local-only-change-me"
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" \
  -d '{
    "display_name": "openai-prod",
    "provider": "openai",
    "adapter": "openai",
    "secret": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1"
  }'

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.

Next Steps

You have now created the upstream credential resource that models use. Continue with Models 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​

Next Steps​