--- title: "Creates a new identity provider." method: POST path: "/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers" tags: ["Identity Provider"] --- # Creates a new identity provider. `POST /v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers` ## Request - Base URL: `https://api-us.beyondidentity.com` - URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a new identity provider. ## Headers - `x-correlation_id` string, required ## Parameters - `#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/get/parameters/1` (unresolved $ref) - `#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/get/parameters/2` (unresolved $ref) ## Request body - object: Represents an identity provider. - `id` string: A unique identifier identifying an identity provider within a realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the identity's tenant. This is automatically set on creation. This field is immutable and read-only. - `realm_id` string: A unique identifier for the identity's realm. This is automatically set on creation. This field is immutable and read-only. - `display_name` string, required: The human-readable name associated with the identity provider. - `protocol_config` IdentityProviderProtocolConfig, required: OIDC protocol configuration for connecting to an identity provider, and validating the token we received. - `type` 'oidc_idp', required - `client_id` string, required: The OIDC client id. This value is from the identity provider. - `client_secret` string, required: The OIDC client secret. This value is from the identity provider. - `token_scopes` string[], required: The scopes which to request from the identity provider. - `identity_attribute` 'id' | 'email' | 'username' | 'external_id', required: Defines which field should be used to populate the subject field of an id token. - `id` - The user ID is used. - `email` - The user email is used. - `username` - The username is used. - `pkce` 'disabled' | 'plain' | 's256', required: PKCE code challenge methods supported for applications, as defined by [RFC-7636](https://datatracker.ietf.org/doc/html/rfc7636). Allowable values are: - `disabled` : PKCE is disabled for this application. This is the default state if the `pkce` field is left blank. Please note that public OIDC and OAuth2 configured applications MUST enable PKCE support. Confidential clients can leave PKCE disabled if they choose. - `plain` : PKCE is enabled for this application. The server will correlate the `code_challenge` and `code_verifier` between the `authorize` and `token` requests. In this configuration, those fields are required to be identical. This is the lower security option for PKCE support and should only be used by legacy clients, or clients that don't support `s256`. - `s256` : PKCE is enabled for this application, and the server will correlate the `code_challenge` and `code_verifier` between the `authorize` and `token` requests. In this configuration, those fields are required to equate as follows: `code_challenge` = `base64url(sha256(ascii(code_verifier)))`. This is the higher security option and should always be preferred if it is supported by the client. - `jwks_url` string, required: The URL that points to the ".well-known/jwks.json" of the identity provider. Must be a URL. - `token_url` string, required: The URL that points to the "/token" endpoint of the identity provider. Must be a URL. - `authorize_url` string, required: The "/authorize" URL to authenticate against inside of the identity provider. Must be a URL. - `identifying_claim_name` string, required: The name of the claim that specifies the user's identity inside of a token. - `oauth_2_par_enabled` boolean, required: Whether to enable OAuth 2.0 Pushed Authorization Request (PAR) support. See https://datatracker.ietf.org/doc/html/rfc9126 for more details. - `oauth_2_par_endpoint` string, nullable: If `oauth_2_par_enabled` is true, this field is required and must be a valid URL. The URL to send the PAR request to. See https://datatracker.ietf.org/doc/html/rfc9126 for more details. - `claims` string: Claims to request from the identity provider. See https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter for more details. If this field is empty, no claims will be requested. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post', required: The authentication method to use when calling the token endpoint. Supports client_secret_basic (HTTP Basic Auth) and client_secret_post (credentials in POST body). ## Response `200` The identity provider has been created. - IdentityProviderProtocolConfigResponse: OIDC protocol configuration for connecting to an identity provider, and validating the token we received. - `type` 'oidc_idp', required - `client_id` string, required: The OIDC client id. This value is from the identity provider. - `client_secret` string, required: The OIDC client secret. This value is from the identity provider. - `token_scopes` string[], required: The scopes which to request from the identity provider. - `identity_attribute` 'id' | 'email' | 'username' | 'external_id', required: Defines which field should be used to populate the subject field of an id token. - `id` - The user ID is used. - `email` - The user email is used. - `username` - The username is used. - `pkce` 'disabled' | 'plain' | 's256', required: PKCE code challenge methods supported for applications, as defined by [RFC-7636](https://datatracker.ietf.org/doc/html/rfc7636). Allowable values are: - `disabled` : PKCE is disabled for this application. This is the default state if the `pkce` field is left blank. Please note that public OIDC and OAuth2 configured applications MUST enable PKCE support. Confidential clients can leave PKCE disabled if they choose. - `plain` : PKCE is enabled for this application. The server will correlate the `code_challenge` and `code_verifier` between the `authorize` and `token` requests. In this configuration, those fields are required to be identical. This is the lower security option for PKCE support and should only be used by legacy clients, or clients that don't support `s256`. - `s256` : PKCE is enabled for this application, and the server will correlate the `code_challenge` and `code_verifier` between the `authorize` and `token` requests. In this configuration, those fields are required to equate as follows: `code_challenge` = `base64url(sha256(ascii(code_verifier)))`. This is the higher security option and should always be preferred if it is supported by the client. - `jwks_url` string, required: The URL that points to the ".well-known/jwks.json" of the identity provider. Must be a URL. - `token_url` string, required: The URL that points to the "/token" endpoint of the identity provider. Must be a URL. - `authorize_url` string, required: The "/authorize" URL to authenticate against inside of the identity provider. Must be a URL. - `redirect_url` string, required: Redirect URL provided by Beyond Identity that the IdP can redirect end users to after successful authorize call. This is an OIDC-compliant callback. - `identifying_claim_name` string, required: The name of the claim that specifies the user's identity inside of a token. - `oauth_2_par_enabled` boolean, required: Whether to enable OAuth 2.0 Pushed Authorization Request (PAR) support. See https://datatracker.ietf.org/doc/html/rfc9126 for more details. - `oauth_2_par_endpoint` string, nullable: If `oauth_2_par_enabled` is true, this field is required and must be a valid URL. The URL to send the PAR request to. See https://datatracker.ietf.org/doc/html/rfc9126 for more details. - `claims` string: Claims to request from the identity provider. See https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter for more details. If this field is empty, no claims will be requested. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post', required: The authentication method to use when calling the token endpoint. Supports client_secret_basic (HTTP Basic Auth) and client_secret_post (credentials in POST body). ## Other responses - `400`: The request is malformed. - `401`: An invalid Authorization token has been supplied. - `403`: The supplied authorization token doesn't allow the requested operation. - `500`: Internal server error. ## Changes - **2026-11-06** `42f3cac49392`: 1 breaking, 7 info - added the new required request property `protocol_config/allOf[#/components/schemas/IdentityProviderProtocolConfig]/oneOf[#/components/schemas/IdentityProviderProtocolConfigOidcIdp]/oauth_2_par_enabled` - added the new optional request property `protocol_config/allOf[#/components/schemas/IdentityProviderProtocolConfig]/oneOf[#/components/schemas/IdentityProviderProtocolConfigOidcIdp]/claims` - added the new optional request property `protocol_config/allOf[#/components/schemas/IdentityProviderProtocolConfig]/oneOf[#/components/schemas/IdentityProviderProtocolConfigOidcIdp]/oauth_2_par_endpoint` - added the new required request property `protocol_config/allOf[#/components/schemas/IdentityProviderProtocolConfig]/oneOf[#/components/schemas/IdentityProviderProtocolConfigOidcIdp]/token_endpoint_auth_method` with a default value - …4 more [Operation history](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/changes/v1/tenants/:tenant_id/realms/:realm_id/identity-providers/post.md) --- [API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/revisions/42f3cac49392?raw)