Update Claim Mapping

PATCH /environments/{env_id}/claim_mappings/{claim_mapping_id}

Update Claim Mapping

Update selected fields on a claim mapping. The mapping name is fixed at creation — delete and recreate the mapping to change it. Changes take effect on new requests without a gateway restart.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.
• claim_mapping_id (path, string, required): Claim mapping ID within the environment.

Request body

Content type: application/json

• jwt_provider (string, optional): 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.

• match (array, optional): Replacement 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, optional): 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

• 200: OK

• 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 PATCH /environments/{env_id}/claim_mappings/{claim_mapping_id}, response 400 above.

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

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

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

cURL

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