--- title: "Create an AI Gateway Identity Provider" method: POST path: "/v1/ai-gateways/{gatewayId}/identity" tags: ["AI Gateway Identity Providers"] --- # Create an AI Gateway Identity Provider `POST /v1/ai-gateways/{gatewayId}/identity` **Pre-release Endpoint** This endpoint is currently in beta and is subject to change. Registers a new identity provider for the AI Gateway. ## Request body - union — **Pre-release Feature** This feature is currently in beta and is subject to change. - AIGatewayIdentityProviderKeyAuth — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for an identity provider. - `display_name` string, required — The display name for this identity provider instance. - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID. - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `type` 'key-auth', required - `config` object — Configuration for the Kong Key auth identity provider. For advanced use cases, additional config properties can be sent in the request body. See: https://developer.konghq.com/plugins/key-auth/reference/ for the list of properties - `hide_credentials` boolean — An optional boolean value telling the plugin to show or hide the credential from the upstream service. If true, the plugin strips the credential from the request. - `key_in_body` boolean — If enabled, reads the request body. Supported MIME types: application/www-form-urlencoded, application/json, and multipart/form-data. - `key_in_header` boolean — If enabled (default), the plugin reads the request header and tries to find the key in it. - `key_in_query` boolean — If enabled (default), the plugin reads the query parameter in the request and tries to find the key in it. - `key_names` string[] — An array of strings containing the names of the keys to look for in the request. - `principals` object — Authenticate against Kong Identity instead of local credentials. Mutually exclusive with identity realms. - `enabled` boolean — When true, authenticate against Kong Identity instead of local credentials. - `directory` string — The Kong Identity directory instance to authenticate against. - `error_on_miss` boolean — When true (default), reject the request if no matching principal is found in Kong Identity. When false, allow the request to continue unauthenticated instead. - AIGatewayIdentityProviderOpenIDConnect — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for an identity provider. - `display_name` string, required — The display name for this identity provider instance. - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID. - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `type` 'openid-connect', required - `config` object — Configuration for the OpenID Connect identity provider. For advanced use cases, additional config properties can be sent in the request body. See: https://developer.konghq.com/plugins/openid-connect/reference/ for the list of properties - `auth_methods` string[] — Types of credentials/grants to enable. - `client_id` string[] — An array of strings representing the client id for the OpenID Connect provider. When multiple values are provided, the client ID and secrets pairs correspond based on their locations in the array. - `client_secret` string[] — An array of strings representing the client secret for the OpenID Connect provider. When multiple values are provided, the client ID and secrets pairs correspond based on their locations in the array. - `client_alg` string[] — Algorithm to use for `client_secret_jwt` or `private_key_jwt` authentication. - `client_auth` string[] — Client authentication methods used with the identity provider. - `consumer_claims` array[] — An array containing an array of string paths representing the location of the claim in a nested object. For example, to map to user.info.id, set [ "user", "info", "id" ]. - string[] - `consumer_groups_claim` string[] — The claim used for consumer groups mapping. If multiple values are set, it means the claim is inside a nested object of the token payload. - `consumer_groups_optional` boolean — Do not terminate the request if consumer groups mapping fails. - `consumer_by` string[] — Consumer fields used when mapping a token claim to a Kong consumer. - `consumer_optional` boolean — Do not terminate the request if consumer mapping fails. - `credential_claim` string[] — Claim path used to derive virtual credentials when consumer mapping is not used. - `issuer` string — URL that identifies the OpenID Provider - `introspection_endpoint` string, uri — Overrides the introspection endpoint returned by discovery. - `mtls_introspection_endpoint` string, uri — mTLS alias for the introspection endpoint. - `cache_introspection` boolean — Cache introspection endpoint requests. - `jwks_endpoint` string, uri — Overrides the JWKS endpoint returned by discovery. - `leeway` integer — Leeway, in seconds, for validating token time claims. - `scopes` string[] — This field is referenceable. - `audience_required` string[] — Audiences required in the access token or introspection response. - `ssl_verify` boolean - `hide_credentials` boolean — Remove credentials used for authentication before proxying the request upstream. - `keepalive` boolean — Reuse HTTP client connections for identity provider requests. - `timeout` integer — Network I/O timeout, in milliseconds, for identity provider requests. - `http_version` 1 | 1.1 — HTTP version used for identity provider requests. - `http_proxy` string, uri — HTTP proxy used for identity provider requests. - `http_proxy_authorization` string — Authorization header value sent to the HTTP proxy. - `https_proxy` string, uri — HTTPS proxy used for identity provider requests. - `https_proxy_authorization` string — Authorization header value sent to the HTTPS proxy. - `no_proxy` string — Comma-separated hosts that bypass the configured proxies. - `upstream_headers` object[] — Map token claims to upstream headers using path-based access. - `header` string, required — The name of the header. - `path` string[], required — The path of the header value. - `cache_tokens_salt` string, required — Salt used for generating the cache key that is used for caching the token endpoint requests. - `principals` object — Map a request to a Kong Identity principal after token verification. - `enabled` boolean — When true, look up a Kong Identity principal after token verification. - `directory` string — The Kong Identity directory instance to look up against. - `principal_by` string — Custom identity name for a custom Kong Identity lookup. When absent and principal_claim is set, a lookup is performed using principal_claim as the claim name instead of the default sub claim. - `principal_claim` string[] — Token claim used for the Kong Identity lookup. If multiple values are set, the claim is inside a nested object of the token payload. Used together with, or instead of, principal_by. - `match_consumer` boolean — If a consumer is attached to the matched principal, load it and set it in the request context, overriding consumer_by. - `match_consumer_groups` boolean — If consumer groups are attached to the matched principal, load them, overriding consumer_groups_claim. - `error_on_miss` boolean — When true (default), reject the request if no principal is matched in Kong Identity after token verification. When false, the request continues without an authenticated principal set. ## Response `201` Identity Provider created successfully. - union — **Pre-release Feature** This feature is currently in beta and is subject to change. - AIGatewayIdentityProviderKeyAuthResponse — **Pre-release Feature** This feature is currently in beta and is subject to change. - `display_name` string, required — The display name for this identity provider instance. - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID. - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `type` 'key-auth', required - `config` object — Configuration for the Kong Key auth identity provider. For advanced use cases, additional config properties can be sent in the request body. See: https://developer.konghq.com/plugins/key-auth/reference/ for the list of properties - `hide_credentials` boolean — An optional boolean value telling the plugin to show or hide the credential from the upstream service. If true, the plugin strips the credential from the request. - `key_in_body` boolean — If enabled, reads the request body. Supported MIME types: application/www-form-urlencoded, application/json, and multipart/form-data. - `key_in_header` boolean — If enabled (default), the plugin reads the request header and tries to find the key in it. - `key_in_query` boolean — If enabled (default), the plugin reads the query parameter in the request and tries to find the key in it. - `key_names` string[] — An array of strings containing the names of the keys to look for in the request. - `principals` object — Authenticate against Kong Identity instead of local credentials. Mutually exclusive with identity realms. - `enabled` boolean — When true, authenticate against Kong Identity instead of local credentials. - `directory` string — The Kong Identity directory instance to authenticate against. - `error_on_miss` boolean — When true (default), reject the request if no matching principal is found in Kong Identity. When false, allow the request to continue unauthenticated instead. - `id` string, uuid, required — Contains a unique identifier used for this resource. - `created_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity update date. - AIGatewayIdentityProviderOpenIDConnectResponse — **Pre-release Feature** This feature is currently in beta and is subject to change. - `display_name` string, required — The display name for this identity provider instance. - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID. - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `type` 'openid-connect', required - `config` object — Configuration for the OpenID Connect identity provider. For advanced use cases, additional config properties can be sent in the request body. See: https://developer.konghq.com/plugins/openid-connect/reference/ for the list of properties - `auth_methods` string[] — Types of credentials/grants to enable. - `client_id` string[] — An array of strings representing the client id for the OpenID Connect provider. When multiple values are provided, the client ID and secrets pairs correspond based on their locations in the array. - `client_secret` string[] — An array of strings representing the client secret for the OpenID Connect provider. When multiple values are provided, the client ID and secrets pairs correspond based on their locations in the array. - `client_alg` string[] — Algorithm to use for `client_secret_jwt` or `private_key_jwt` authentication. - `client_auth` string[] — Client authentication methods used with the identity provider. - `consumer_claims` array[] — An array containing an array of string paths representing the location of the claim in a nested object. For example, to map to user.info.id, set [ "user", "info", "id" ]. - string[] - `consumer_groups_claim` string[] — The claim used for consumer groups mapping. If multiple values are set, it means the claim is inside a nested object of the token payload. - `consumer_groups_optional` boolean — Do not terminate the request if consumer groups mapping fails. - `consumer_by` string[] — Consumer fields used when mapping a token claim to a Kong consumer. - `consumer_optional` boolean — Do not terminate the request if consumer mapping fails. - `credential_claim` string[] — Claim path used to derive virtual credentials when consumer mapping is not used. - `issuer` string — URL that identifies the OpenID Provider - `introspection_endpoint` string, uri — Overrides the introspection endpoint returned by discovery. - `mtls_introspection_endpoint` string, uri — mTLS alias for the introspection endpoint. - `cache_introspection` boolean — Cache introspection endpoint requests. - `jwks_endpoint` string, uri — Overrides the JWKS endpoint returned by discovery. - `leeway` integer — Leeway, in seconds, for validating token time claims. - `scopes` string[] — This field is referenceable. - `audience_required` string[] — Audiences required in the access token or introspection response. - `ssl_verify` boolean - `hide_credentials` boolean — Remove credentials used for authentication before proxying the request upstream. - `keepalive` boolean — Reuse HTTP client connections for identity provider requests. - `timeout` integer — Network I/O timeout, in milliseconds, for identity provider requests. - `http_version` 1 | 1.1 — HTTP version used for identity provider requests. - `http_proxy` string, uri — HTTP proxy used for identity provider requests. - `http_proxy_authorization` string — Authorization header value sent to the HTTP proxy. - `https_proxy` string, uri — HTTPS proxy used for identity provider requests. - `https_proxy_authorization` string — Authorization header value sent to the HTTPS proxy. - `no_proxy` string — Comma-separated hosts that bypass the configured proxies. - `upstream_headers` object[] — Map token claims to upstream headers using path-based access. - `header` string, required — The name of the header. - `path` string[], required — The path of the header value. - `cache_tokens_salt` string, required — Salt used for generating the cache key that is used for caching the token endpoint requests. - `principals` object — Map a request to a Kong Identity principal after token verification. - `enabled` boolean — When true, look up a Kong Identity principal after token verification. - `directory` string — The Kong Identity directory instance to look up against. - `principal_by` string — Custom identity name for a custom Kong Identity lookup. When absent and principal_claim is set, a lookup is performed using principal_claim as the claim name instead of the default sub claim. - `principal_claim` string[] — Token claim used for the Kong Identity lookup. If multiple values are set, the claim is inside a nested object of the token payload. Used together with, or instead of, principal_by. - `match_consumer` boolean — If a consumer is attached to the matched principal, load it and set it in the request context, overriding consumer_by. - `match_consumer_groups` boolean — If consumer groups are attached to the matched principal, load them, overriding consumer_groups_claim. - `error_on_miss` boolean — When true (default), reject the request if no principal is matched in Kong Identity after token verification. When false, the request continues without an authenticated principal set. - `id` string, uuid, required — Contains a unique identifier used for this resource. - `created_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity update date. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `429` — Too Many Requests --- [API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/revisions/b576ea92fca2/schema)