Create Caller API Key

POST /environments/{env_id}/api_keys

Create Caller API Key

Create a caller credential for an environment. The plaintext bearer is returned once in the create response and cannot be recovered later.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.

Request body

Content type: application/json

• display_name (string, required): Human-readable caller API key name.

• allowed_models (array, required): UUIDs of model resources in the target environment this key may address. Empty array denies every model. Granting a routing group / semantic router / ensemble authorizes requests addressed to that entry; its members stay unaddressable unless granted themselves. Granting a wildcard entry (display name containing a single *) authorizes every request whose model name matches the pattern — including a name that also exists as a separately registered, ungranted exact model (the glob grants access; the exact entry still serves the request).

• allowed_agents (array, optional): A2A agents this key may reach, as agent-name patterns. * grants every agent and an exact agent name grants a single agent. Omit or send an empty array to grant no A2A agent access. Each entry may use letters, digits, ., _, -, and *; other characters are rejected.

• allowed_routes (array, optional): Passthrough routes this key may use, as route-name patterns. * grants every route and an exact route name grants a single route. Omit or send an empty array to grant no passthrough-route access. Each entry may use letters, digits, ., _, -, and *; other characters are rejected.

• mcp_access (object, optional): The key's own layer of the MCP tool ACL, intersected with the environment and team layers. Omit for a key that adds no constraint of its own — but note that a key with no layer anywhere has no MCP tool access, since access is granted explicitly.

• allOf variant 1

• mcp_access.allow (array, required): Namespaced server__tool patterns this key allows (*, server__*, or an exact server__tool). Each entry may use letters, digits, ., _, -, and *; other characters are rejected. An empty list leaves the key no MCP tool access; ["*"] narrows nothing, which is what a key that only means to subtract tools sends alongside deny.

• mcp_access.deny (array, optional): Namespaced server__tool patterns removed from the key's effective grant, matched the same way as allow. Deny always wins over any allow, on any layer.

• mcp_rate_limits (object, optional): Per-MCP-server limits for this key, keyed by MCP server name. Each server named here gets its own counter, so exhausting one server's allowance leaves the others untouched, and rate_limit still applies on top. Servers that are not named are bounded by rate_limit alone. A name that matches no registered MCP server is accepted and takes effect if a server is later registered under it.

• mcp_rate_limits.*.rps (integer, optional): Tool calls per second.

• mcp_rate_limits.*.rpm (integer, optional): Tool calls per minute.

• mcp_rate_limits.*.rph (integer, optional): Tool calls per hour.

• mcp_rate_limits.*.rpd (integer, optional): Tool calls per day.

• mcp_rate_limits.*.concurrency (integer, optional): Maximum in-flight tool calls to this MCP server.

• rate_limit (object, optional): Per-key rate limit.

• allOf variant 1

• rate_limit.rps (integer, optional): Requests per second.

• rate_limit.rpm (integer, optional): Requests per minute.

• rate_limit.rph (integer, optional): Requests per hour.

• rate_limit.rpd (integer, optional): Requests per day.

• rate_limit.tpm (integer, optional): Tokens per minute.

• rate_limit.tpd (integer, optional): Tokens per day.

• rate_limit.concurrency (integer, optional): Maximum in-flight requests.

• team_id (string, optional): Team binding used for attribution and policy scope.

• user_id (string, optional): Organization member this key is attributed to, given as the membership id from GET /members — not that member's user_id, which is a different identifier and is rejected here as an unknown member. Binding a key attributes its traffic to the member and brings the member's limits and budgets into scope. When team_id is also set, the member must belong to that team.

• key (string, optional): Caller-supplied plaintext bearer. The AISIX control plane generates one when this field is not supplied. The value is trimmed, stored as a SHA-256 hash, and returned only once in the create response.

• jwt_subject (string, optional): External identity bound to this key for JWT authentication, matched against the identity claim of tokens issued by the OIDC provider named in jwt_provider. Set together with jwt_provider; the pair is unique within the environment.

• jwt_provider (string, optional): Name of the OIDC provider permitted to assert this key's jwt_subject. Required when jwt_subject is set.

• expires_at (string, optional): Expiry deadline. Omit or send null for a key that never expires. Once the deadline passes, the gateway rejects the bearer with 401.

Responses

• 201: Created. The body carries the plaintext bearer once; persist it on the caller side immediately.

• api_key (object, required): Caller credential metadata. The plaintext bearer is returned only in the create response.

• api_key.id (string, required): Caller API key ID.

• api_key.env_id (string, required): Environment ID that owns this caller API key.

• api_key.display_name (string, required): Human-readable caller API key name.

• api_key.allowed_models (array, required): UUIDs of model resources in the same environment this key may address. Empty array denies every model. Granting a routing group / semantic router / ensemble authorizes requests addressed to that entry; its members stay unaddressable unless granted themselves. Granting a wildcard entry (display name containing a single *) authorizes every request whose model name matches the pattern — including a name that also exists as a separately registered, ungranted exact model (the glob grants access; the exact entry still serves the request).

• api_key.allowed_agents (array, optional): A2A agents this key may reach, as agent-name patterns. * grants every agent and an exact agent name grants a single agent. Absent grants no A2A agent access; access is explicit. Present only when at least one pattern is set.

• api_key.allowed_routes (array, optional): Passthrough routes this key may use, as route-name patterns. * grants every route and an exact route name grants a single route. Absent grants no passthrough-route access; access is explicit. Present only when at least one pattern is set.

• api_key.mcp_access (object, optional): The key's own layer of the MCP tool ACL, intersected with the environment and team layers. Absent means the key adds no constraint of its own.

• allOf variant 1

• api_key.mcp_access.allow (array, required): Namespaced server__tool patterns this key allows (*, server__*, or an exact server__tool). Each entry may use letters, digits, ., _, -, and *; other characters are rejected. An empty list leaves the key no MCP tool access; ["*"] narrows nothing, which is what a key that only means to subtract tools sends alongside deny.

• api_key.mcp_access.deny (array, optional): Namespaced server__tool patterns removed from the key's effective grant, matched the same way as allow. Deny always wins over any allow, on any layer.

• api_key.mcp_rate_limits (object, optional): Per-MCP-server limits for this key, keyed by MCP server name. Present only when at least one server is limited.

• api_key.mcp_rate_limits.*.rps (integer, optional): Tool calls per second.

• api_key.mcp_rate_limits.*.rpm (integer, optional): Tool calls per minute.

• api_key.mcp_rate_limits.*.rph (integer, optional): Tool calls per hour.

• api_key.mcp_rate_limits.*.rpd (integer, optional): Tool calls per day.

• api_key.mcp_rate_limits.*.concurrency (integer, optional): Maximum in-flight tool calls to this MCP server.

• api_key.rate_limit (object, optional): Per-key rate limit. null means no key-level limit.

• allOf variant 1

• api_key.rate_limit.rps (integer, optional): Requests per second.

• api_key.rate_limit.rpm (integer, optional): Requests per minute.

• api_key.rate_limit.rph (integer, optional): Requests per hour.

• api_key.rate_limit.rpd (integer, optional): Requests per day.

• api_key.rate_limit.tpm (integer, optional): Tokens per minute.

• api_key.rate_limit.tpd (integer, optional): Tokens per day.

• api_key.rate_limit.concurrency (integer, optional): Maximum in-flight requests.

• api_key.team_id (string, optional): Team binding used for attribution and policy scope.

• api_key.user_id (string, optional): Organization member this key is attributed to — the membership id from GET /members, not that member's user_id.

• api_key.jwt_subject (string, optional): External identity bound to this key for JWT authentication. When a request presents a valid JWT from the OIDC provider named in jwt_provider, that provider's identity claim selects the key whose jwt_subject equals it, and the request runs with this key's permissions, rate limits, and budget. The jwt_provider and jwt_subject pair is unique within the environment.

• api_key.jwt_provider (string, optional): Name of the OIDC provider permitted to assert this key's jwt_subject. A token is only ever mapped to this key when issued by the named provider, so a second trusted provider cannot impersonate this identity. Set together with jwt_subject.

• api_key.expires_at (string, optional): Expiry deadline. Present only when set; absent for keys that never expire. Once the deadline passes, the gateway rejects the bearer with 401.

• api_key.disabled (boolean, required): Administratively disabled. A disabled key is rejected by the gateway with 401 until re-enabled; the underlying bearer is preserved.

• api_key.status (string, required): Derived lifecycle state: disabled wins over expired; a key is expired once expires_at has passed; otherwise active.

• api_key.created_at (string, required): Time when the caller API key was created.

• api_key.updated_at (string, required): Time when the caller API key was last updated.

• plaintext (string, required): The plaintext bearer the caller must include on gateway requests as Authorization: Bearer <plaintext>. Persist this on the client side immediately. There is no recovery path on the server.

• warnings (array, optional): Data-plane compatibility warnings for this save, when any connected data plane predates a configured capability (e.g. allowed_routes on a pre-0.10.0 fleet).

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to POST /environments/{env_id}/api_keys, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to POST /environments/{env_id}/api_keys, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to POST /environments/{env_id}/api_keys, response 400 above.

• 409: Request conflicts with current resource state. Response fields (application/json): identical to POST /environments/{env_id}/api_keys, response 400 above.

cURL

curl -X POST '$AISIX_CP/environments/{env_id}/api_keys' -H 'Authorization: Bearer $AISIX_TOKEN'