Caller API Keys

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

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 Credentials and Model Aliases first.

Create a Caller API Key

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

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

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, ensemble, and semantic-router models available to the caller API key. Multi-target routing 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.

Import Existing Keys from Another Gateway

When moving from another AI gateway, import existing caller API keys so applications can keep using the same credentials after moving to AISIX. In self-hosted AISIX, create each API key resource from the SHA-256 hash of the existing plaintext key. AISIX authenticates a request by hashing the incoming bearer token, so existing key values do not need an AISIX-specific prefix, length, or character set.

To import a key, use the existing value as the plaintext key in the create flow above. Hash the value and create the API key resource with that key_hash and the model aliases the key should reach. For a bulk import, repeat the same request for each key. Because key_hash is unique, re-running an import returns a conflict for keys that already exist, which makes the import safe to retry.

In the AISIX managed control plane, you do not hash imported keys yourself. When creating an API key, provide the existing key as a custom value, and AISIX stores its hash. Administrators can control whether custom API key values are allowed. When custom values are disabled, every key must be auto-generated.

Set an Expiration

Caller API keys never expire by default. Set expires_at to an RFC 3339 timestamp when a key should stop working at a deadline.

After the deadline passes, the proxy rejects the key with 401 and the error code api_key_expired. AISIX evaluates expiration on every request, so the key becomes invalid at the deadline without a restart or configuration change.

Set the expiration at create time:

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"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

To change the deadline on an existing key, update it with PUT. Send the full API key resource and change only the expires_at value:

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

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/${API_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": ["gpt-4o-prod"],
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Setting an expiration does not affect the key before the deadline. A key with a future expires_at authenticates normally.

To make the key permanent again, send a full PUT update that omits expires_at. Because PUT replaces the resource, include every field you want to keep, such as key_hash, allowed_models, rate_limit, or allowed_tools.

Disable and Re-enable a Caller API Key

Disabling pauses a key without deleting it. The proxy rejects a disabled key with 401 and the error code api_key_disabled. The key value is preserved, so re-enabling restores the exact credential the application already holds.

Pause access with a full-resource update:

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

To re-enable the key, send the same request with disabled set to false, or omit the field. Because PUT replaces the resource, keep the model allowlist and any limits in the request body.

Disable a key for incident response or temporary access pauses where the caller may come back. Use rotation when the plaintext may have leaked, and delete the key when the caller is gone for good.

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.

If you use the AISIX managed control plane, the API keys page provides the same lifecycle actions. It shows whether a key is Active, Expired, or Disabled. You can set or clear expiration, disable or re-enable a key, and rotate a key from the same page. AISIX shows the new plaintext value once during rotation.

For API automation, the AISIX Cloud Admin API accepts the same lifecycle fields on PATCH. Send "expires_at": null to clear a deadline. Each lifecycle change is recorded in the organization's audit log.

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.