Create Claim Mapping

POST /environments/{env_id}/claim_mappings

Create Claim Mapping

Create a rule that resolves verified JWT claims to an existing caller API key. When a token passes an OIDC provider's verification and no key binds its subject via jwt_subject, the enabled mappings naming that provider are evaluated in priority order (lower first, ties broken by name) and the first mapping whose match conditions all hold selects the API key the request runs as — with that key's model and tool access, rate limits, and budget. A token matching no mapping is rejected. The mapping name is unique within the environment and cannot be changed after creation. The referenced OIDC provider and API key must already exist in the environment.

Parameters

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

Request body

Content type: application/json

• name (string, required): Human-readable mapping name, unique within the environment.

• jwt_provider (string, required): Name of an existing OIDC provider in this environment whose tokens this mapping applies to.

• priority (integer, optional): Evaluation order among the provider's mappings: lower values are evaluated first, ties are broken by name.

• match (array, required): Claim conditions, all of which must hold for the mapping to match.

• match[].claim (string, required): Claim to inspect. Dots traverse nested objects (for example realm_access.roles). A missing claim never matches.

• match[].op (string, required): Comparison operator. exact requires a string claim equal to one of values; contains requires an array claim containing one of them. A claim whose type does not fit the operator never matches.

• match[].values (array, required): Accepted values; the condition holds when any one matches.

• resolve (object, required): What a matched mapping resolves to.

• resolve.api_key_id (string, required): ID of the API key the request runs as. The key's model and tool access, rate limits, and budget apply exactly as if the caller had presented the key itself.

• enabled (boolean, optional): Whether the mapping participates in evaluation.

Responses

• 201: Created

• claim_mapping (object, required): A rule resolving verified JWT claims to an existing caller API key. Evaluated only when no key binds the token's subject directly via jwt_subject.

• claim_mapping.id (string, required): Unique claim mapping ID.

• claim_mapping.env_id (string, required): Environment the mapping belongs to.

• claim_mapping.name (string, required): Human-readable mapping name, unique within the environment. Fixed at creation.

• claim_mapping.jwt_provider (string, required): Name of the OIDC provider whose tokens this mapping applies to. A mapping never matches a token verified by a different provider.

• claim_mapping.priority (integer, required): Evaluation order among the provider's mappings: lower values are evaluated first, ties are broken by name.

• claim_mapping.match (array, required): Claim conditions, all of which must hold for the mapping to match.

• claim_mapping.match[].claim (string, required): Claim to inspect. Dots traverse nested objects (for example realm_access.roles). A missing claim never matches.

• claim_mapping.match[].op (string, required): Comparison operator. exact requires a string claim equal to one of values; contains requires an array claim containing one of them. A claim whose type does not fit the operator never matches.

• claim_mapping.match[].values (array, required): Accepted values; the condition holds when any one matches.

• claim_mapping.resolve (object, required): What a matched mapping resolves to.

• claim_mapping.resolve.api_key_id (string, required): ID of the API key the request runs as. The key's model and tool access, rate limits, and budget apply exactly as if the caller had presented the key itself.

• claim_mapping.enabled (boolean, required): Whether the mapping participates in evaluation. A disabled mapping is kept but skipped.

• claim_mapping.created_at (string, required): Creation timestamp.

• claim_mapping.updated_at (string, required): Last update timestamp.

• warnings (array, optional): Present on save operations when some data plane nodes in the environment run a gateway version that does not execute claim mappings at all — the saved rule has no effect there and matching tokens are rejected. Never present on reads.

• 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}/claim_mappings, response 400 above.

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

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

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

cURL

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