Create an AI API key

POST /aisix/admin/apikeys

Interactive request editor loads with JavaScript.

Query Parameters

ai_gateway_group_id*string

AI Gateway group ID (filter resources by group).

Length1 <= length

Request Body

application/json

name?string

Optional human-readable label for the API key (control-plane only, not written to the data plane).

Lengthlength <= 256

key*string

The secret key value used for authentication.

Length1 <= length <= 256

allowed_models*array<string>

Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.

rate_limit?

Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).

Response Body

`application/json`

curl -X POST "$API_BASE_URL/aisix/admin/apikeys?ai_gateway_group_id=abc1234567890" \  -H "Content-Type: application/json" \  -d '{    "key": "my-secret-key-value",    "allowed_models": [      "openai/gpt-4o"    ]  }'

Successfully retrieved or modified the AI API key.

{
  "value": {
    "id": "apikey-abc123",
    "ai_gateway_group_id": "group-abc123",
    "name": "my-app-key",
    "key": "my-secret-key-value",
    "allowed_models": [
      "openai/gpt-4o"
    ],
    "rate_limit": {
      "tpm": 1,
      "tpd": 1,
      "rpm": 1,
      "rpd": 1,
      "concurrency": 1
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.

{
  "value": {},
  "error_msg": "error message"
}

Conflict — A resource with the same unique identifier (e.g., name) already exists.

{
  "value": {},
  "error_msg": "error message"
}

Complete operation details and schema variants

IAM Action: ai_gateway:CreateAIAPIKey, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Creates a new AI API key in the specified AI Gateway group. The key will be synced to the aisix data plane via etcd.

Parameters

ai_gateway_group_id (query, string, required): AI Gateway group ID (filter resources by group).

Request body

Content type: application/json

name (string, optional): Optional human-readable label for the API key (control-plane only, not written to the data plane).
key (string, required): The secret key value used for authentication.
allowed_models (array, required): Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.
rate_limit (object, optional): Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).
rate_limit.tpm (integer, optional): Maximum tokens allowed per minute (token_per_minute).
rate_limit.tpd (integer, optional): Maximum tokens allowed per day (token_per_day).
rate_limit.rpm (integer, optional): Maximum requests allowed per minute (request_per_minute).
rate_limit.rpd (integer, optional): Maximum requests allowed per day (request_per_day).
rate_limit.concurrency (integer, optional): Maximum concurrent requests allowed.

Responses

200: Successfully retrieved or modified the AI API key.
allOf variant 1
value (object, optional): The specific resource.
allOf variant 2
value (object, optional): API key that grants access to aisix proxy endpoints.
value.id (string, optional): Unique API key ID.
value.ai_gateway_group_id (string, optional): ID of the AI Gateway group this API key belongs to (control-plane only).
value.name (string, optional): Optional human-readable label for the API key (control-plane only, not written to etcd).
value.key (string, optional): The secret key value used for authentication.
value.allowed_models (array, optional): List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.
value.rate_limit (object, optional): Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).
value.rate_limit.tpm (integer, optional): Maximum tokens allowed per minute (token_per_minute).
value.rate_limit.tpd (integer, optional): Maximum tokens allowed per day (token_per_day).
value.rate_limit.rpm (integer, optional): Maximum requests allowed per minute (request_per_minute).
value.rate_limit.rpd (integer, optional): Maximum requests allowed per day (request_per_day).
value.rate_limit.concurrency (integer, optional): Maximum concurrent requests allowed.
value.created_at (string, optional): Timestamp when the API key was created.
value.updated_at (string, optional): Timestamp when the API key was last updated.
400: Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.
value (object, optional): The specific resource.
error_msg (string, optional): The error message.
409: Conflict — A resource with the same unique identifier (e.g., name) already exists. Response fields (application/json): identical to POST /aisix/admin/apikeys, response 400 above.

cURL

curl -X POST '$API_BASE_URL/aisix/admin/apikeys'

Create an AI API key

200application/json

400application/json

409application/json

`application/json`

`application/json`

`application/json`