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 credentials operators use to manage resources. Applications send the plaintext caller API key to AISIX, and AISIX stores only the SHA-256 hash in the API key resource.

This guide covers applications that present the plaintext key. To let an application present short-lived credentials from an external identity provider instead, configure JWT Authentication. AISIX maps a verified JWT identity to a caller API key, so the key's access and traffic controls still apply. In AISIX Cloud, matching budgets also apply.

The examples cover both management paths. AISIX Cloud can generate the plaintext value, while the open-source AISIX gateway derives the hash from an environment variable or accepts a precomputed hash in its resources file.

Prerequisites

Before starting, prepare the following:

• A model alias the caller should be allowed to use. If you have not created one yet, configure Provider Keys and Model Aliases first.
• 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, the declarative resources file that contains the model alias.

Create a Caller API Key

Configure the caller credential using the management path for your deployment.

AISIX Cloud

Export the AISIX Cloud connection details and the ID of the model the caller may use:

# 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"
export MODEL_ID="YOUR_MODEL_ID"

MODEL_ID is the id returned when you created the model alias, not the alias name.

Create the API key resource with the allowed model. AISIX Cloud generates the plaintext key and returns it once in the create response:

RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "chat-app",
    "allowed_models": ["'"$MODEL_ID"'"]
  }')

export API_KEY_ID=$(echo "$RESPONSE" | jq -r '.api_key.id')
export AISIX_API_KEY=$(echo "$RESPONSE" | jq -r '.plaintext')
echo "$RESPONSE" | jq

You should see a response similar to the following:

{
  "api_key": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "env_id": "9be9891a-6a53-4bd8-a897-a03fe38a1ca5",
    "display_name": "chat-app",
    "allowed_models": [
      "6a3f2c1d-8f4e-49b2-b6f1-3f6f24d0f9a2"
    ],
    "disabled": false,
    "status": "active",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  },
  "plaintext": "sk-***"
}

The highlighted id identifies the key when you update, rotate, or delete it later. The highlighted plaintext is the caller credential. It is returned only in this response and cannot be recovered later, so store it securely and configure the application with it now. The key projects to attached gateways automatically.

Open-Source AISIX Gateway

Choose a plaintext caller credential and make it available to the gateway process:

export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Add an entry to the api_keys collection. The key_env value is the name of the environment variable, not the credential itself:

resources.yaml

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod

The gateway resolves allowed_models by model display_name and stores the environment variable's SHA-256 hash in the active resource. Validate the complete resources file before applying it. If CALLER_API_KEY was already available to the running gateway process, send SIGHUP to reload the file. If you introduced the variable now, restart or recreate the gateway with the variable so the process can resolve it.

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	AISIX Cloud	Open-source AISIX gateway	Use when
Specific models	List model resource IDs from the same environment, such as ["$MODEL_ID"].	List model aliases from the same resources file, such as ["gpt-4o-prod"]. Single-* glob patterns are also supported.	The application should call only approved model aliases.
No model access	Use [].	Use [].	You want to create the key before granting model access.

The model list endpoint uses the same allowlist. It returns every concrete direct or virtual alias available to the caller API key, including routing, semantic, and ensemble aliases. Wildcard aliases are not returned because they are patterns rather than concrete model names.

Verify Access

Export the gateway origin:

# AISIX_PROXY is the gateway origin; omit a trailing slash and endpoint path.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

The AISIX Cloud creation example already saved the generated plaintext in AISIX_API_KEY. For the open-source AISIX gateway, use the plaintext value assigned to CALLER_API_KEY:

# Open-source AISIX gateway only.
export AISIX_API_KEY="$CALLER_API_KEY"

The caller sends the model alias name and the plaintext key:

curl -sS -X POST "$AISIX_PROXY/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.

List the models visible to the caller and confirm that the configured alias appears:

curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

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. 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.

In AISIX Cloud, provide the existing plaintext value in the key field instead of letting the control plane generate one:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "imported-caller",
    "allowed_models": ["'"$MODEL_ID"'"],
    "key": "YOUR_EXISTING_CALLER_KEY"
  }'

For a bulk AISIX Cloud import, repeat the same request for each key. Re-running an import with the same display_name returns 409 (duplicate name), which makes the import safe to retry. The key value itself is not checked for duplicates, so keep display names stable across retries.

For the open-source AISIX gateway, set the environment variable named by key_env to the existing plaintext value before starting the gateway. To avoid supplying plaintext to the gateway process, set key_hash in the resources file to the lowercase SHA-256 hexadecimal hash instead. Configure exactly one of key_env or key_hash on each caller API key.

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.

AISIX Cloud

Set the expiration at create time:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "expiring-caller",
    "allowed_models": ["'"$MODEL_ID"'"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

To change the deadline on an existing key, update it with PATCH. The update changes only the fields you send:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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 "expires_at": null to clear the deadline.

Open-Source AISIX Gateway

Set the deadline on the caller API key entry:

resources.yaml

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
    expires_at: "2027-01-01T00:00:00Z"

Validate and reload the resources file to add, change, or remove the deadline. Once loaded, the gateway evaluates the deadline on every request.

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.

AISIX Cloud

Pause access with a PATCH update:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": true
  }'

To re-enable the key, send the same request with disabled set to false. Other fields, such as the model allowlist and any limits, are unchanged by the update.

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.

Open-Source AISIX Gateway

Set disabled: true on the caller API key entry, then validate and reload the resources file:

resources.yaml

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
    disabled: true

Set disabled to false, or remove the field, and reload the file to restore access with the same credential.

Rotate a Caller API Key

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

AISIX Cloud

Rotate the API key resource. The request has no body:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $AISIX_TOKEN"

You should see a response similar to the following:

{
  "api_key": {
    "id": "f1ad9f8a-75d0-46ae-9d8d-0cfe8d1d8387",
    "env_id": "9be9891a-6a53-4bd8-a897-a03fe38a1ca5",
    "display_name": "chat-app",
    "allowed_models": [
      "6a3f2c1d-8f4e-49b2-b6f1-3f6f24d0f9a2"
    ],
    "disabled": false,
    "status": "active",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:21:05Z"
  },
  "plaintext": "sk-***"
}

Rotation replaces only the credential. The key resource is preserved: the name, model allowlist, rate limit, bindings, expiry deadline, and disabled state carry over. The highlighted new plaintext is returned once in the rotate response. Store it securely and update the application; the old plaintext stops authenticating when the rotated resource reaches the gateway.

The API keys page in the AISIX dashboard provides the same lifecycle actions. It shows whether a key is Active, Expired, or Disabled, and shows the new plaintext value once during rotation. Each lifecycle change is recorded in the organization audit log.

Open-Source AISIX Gateway

For an immediate switch, replace the value supplied through key_env and restart the gateway so the process receives the new environment value. The old plaintext stops working when the replacement configuration loads.

For a gradual rotation, make both credentials available to the gateway process and declare a second caller API key with the same access:

resources.yaml

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
  - display_name: chat-app-new
    key_env: NEW_CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod

Restart or recreate the gateway if the new environment variable was not already available to its process. After both credentials work, update applications to use the new value, remove the old entry, and validate and reload the resources file. This sequence keeps the old credential available during the caller rollout.

The replacement is a separate caller API key. Copy every access, lifecycle, attribution, and inline rate-limit field that should remain effective, including allowed_tools, allowed_agents, mcp_access, expires_at, team_id, user_id, user_name, and rate_limit when configured. For each rate_limit_policies entry with scope: api_key and scope_ref: chat-app, add a corresponding policy with a unique name and scope_ref: chat-app-new for the overlap period. Remove the old policy only after applications stop using the old key.

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 API Key and Model Rate Limits, Rate Limit Policies, and Budgets.