Create OIDC Provider

POST /environments/{env_id}/oidc_providers

Create OIDC Provider

Register an identity provider the gateway trusts for JWT authentication in this environment. Once at least one enabled provider exists, requests may authenticate with a JWT issued by it instead of an API key: the token's issuer selects the provider, its signature and claims are verified, and the value of identity_claim selects the API key whose jwt_subject matches — the request then runs with that key's permissions, rate limits, and budget. Provider names and issuers are unique within the environment, and the name cannot be changed after creation.

Parameters

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

Request body

Content type: application/json

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

• issuer (string, required): Expected iss claim, compared exactly against the token's issuer. Unique within the environment.

• audiences (array, required): Accepted aud values. A token's audience must contain at least one of these.

• jwks_uri (string, optional): Endpoint the token signing keys are fetched from. Omit to resolve it from the issuer's OIDC discovery document.

• identity_claim (string, optional): Claim whose value selects the API key to act as, matched against each key's jwt_subject. Dots traverse nested objects.

• required_scopes (array, optional): Scopes that must all be present in the token's scope claim.

• bound_claims (object, optional): Claim requirements a token must satisfy, all of which must hold. Keys name claims, with dots traversing nested objects (for example realm_access.roles). Each requirement is satisfied when the claim equals — or, for array claims, contains — the expected value (a single string) or at least one of the expected values (an array of strings).

• oneOf variant 1

• oneOf variant 2

• leeway_secs (integer, optional): Clock-skew allowance in seconds applied to the token's time-based claims.

• enabled (boolean, optional): Whether the provider participates in JWT authentication.

Responses

• 201: Created

• oidc_provider (object, required): An identity provider the gateway trusts for JWT authentication. Requests presenting a JWT issued by an enabled provider run as the API key whose jwt_subject equals the token's identity claim.

• oidc_provider.id (string, required): OIDC provider ID.

• oidc_provider.env_id (string, required): Environment ID that owns this provider.

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

• oidc_provider.issuer (string, required): Expected iss claim, compared exactly against the token's issuer. Tokens whose issuer matches no enabled provider are rejected.

• oidc_provider.audiences (array, required): Accepted aud values. A token's audience must contain at least one of these; tokens without an audience claim are rejected.

• oidc_provider.jwks_uri (string, optional): Endpoint the token signing keys are fetched from. When omitted, the endpoint is resolved from the issuer's OIDC discovery document (<issuer>/.well-known/openid-configuration). Signing-key rotation at the identity provider is picked up automatically.

• oidc_provider.identity_claim (string, required): Claim whose value selects the API key to act as: the request is bound to the key whose jwt_subject equals this claim's value. Dots traverse nested objects.

• oidc_provider.required_scopes (array, required): Scopes that must all be present in the token's scope claim (a space-delimited string or an array of strings). An empty list requires nothing.

• oidc_provider.bound_claims (object, optional): Claim requirements a token must satisfy, all of which must hold. Keys name claims, with dots traversing nested objects (for example realm_access.roles). Each requirement is satisfied when the claim equals — or, for array claims, contains — the expected value (a single string) or at least one of the expected values (an array of strings).

• oneOf variant 1

• oneOf variant 2

• oidc_provider.leeway_secs (integer, required): Clock-skew allowance in seconds applied to the token's time-based claims.

• oidc_provider.enabled (boolean, required): Disabled providers are kept but tokens they issued no longer authenticate.

• oidc_provider.created_at (string, required): Time when the provider was created.

• oidc_provider.updated_at (string, required): Time when the provider was last updated.

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

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

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

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

cURL

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