Caller API Keys

In this guide, you will create a caller API key and allow it to use one or more model aliases.

Caller API keys authenticate applications on the proxy API. They are separate from the admin key used for management requests. Applications send the plaintext caller API key to AISIX, and AISIX stores only the SHA-256 hash in the API key resource.

Prerequisites

Before starting, prepare the following:

• A self-hosted gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• A model alias the caller should be allowed to use. If you have not created one yet, configure Provider Keys and Models first.

Create a Caller API Key

Choose the plaintext key your application will send to AISIX. Hash it before creating the admin resource:

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export AISIX_API_KEY="sk-app-caller"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

Create the API key resource with the hash and the model aliases this caller API key may use:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": ["gpt-4o-prod"]
  }'

You should see a response similar to the following:

{
  "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
  "value": {
    "key_hash": "43d758e3b4aa2aacdb4b49c09c26435fb5083148fda6cfc9c5e38078915c6bdb",
    "allowed_models": [
      "gpt-4o-prod"
    ]
  },
  "revision": 1
}

Copy the highlighted id if you plan to update, rotate, or delete this caller API key later.

Configure the application with the plaintext key. The stored key_hash is not a usable caller credential.

Control Model Access

The model allowlist is the authorization boundary for a caller API key. Choose the narrowest value that matches how the key will be used.

Access Pattern	allowed_models Value	Use When
Specific aliases	["gpt-4o-prod", "chat-prod"]	Most applications should call only approved model aliases.
All visible models	["*"]	A trusted internal key needs broad model access.
No model access	[]	You want to create the key before granting model access.

The model list endpoint uses the same allowlist. It returns the single-target models available to the caller API key. Multi-target aliases are callable when allowed, but they are not included in the model list.

Verify Access

Send a request to an allowed model alias. The caller uses the plaintext key, not the hash:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {"role": "user", "content": "Hello from AISIX."}
    ]
  }'

A successful request reaches the upstream model and returns a chat-completions response. If the proxy returns 401 or 403, check that the application is using the plaintext key and an allowed model alias.

Rotate a Caller API Key

Use key rotation when an existing caller API key needs a new plaintext value.

Set API_KEY_ID to the highlighted id from the create response, then rotate the API key resource:

export API_KEY_ID="f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys/${API_KEY_ID}/rotate" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

You should see a response similar to the following:

{
  "entry": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "value": {
      "key_hash": "4c79f2cc907407e8218346d28c64eb4e8ed4db2a50ea74e75f3a8f5c4f4d0f20",
      "allowed_models": [
        "gpt-4o-prod"
      ]
    },
    "revision": 2
  },
  "plaintext": "sk-***"
}

The rotate response is the only time AISIX returns the highlighted plaintext key. Store it securely and update the application to use the new value. Later reads return only the hash.

Next Steps

You have now configured how a caller authenticates and which model aliases it can use. Continue with Routing and Failover when one model alias should select from multiple upstream targets.

To add caller-specific limits or shared policy controls, see Rate Limits and Budgets.