--- title: "Create a New Application" method: POST path: "/v1/tenants/{tenant_id}/realms/{realm_id}/applications" tags: ["Applications"] --- # Create a New Application `POST /v1/tenants/{tenant_id}/realms/{realm_id}/applications` ## Request - Base URL: `https://api-us.beyondidentity.com` - URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) To create an application, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/applications`. Values in the request body for read-only fields will be ignored. At present, there are only two supported protocol types for applications, `oauth2` and `oidc`. ## Path parameters - `tenant_id` string, required - `realm_id` string, required ## Request body - object: Request for CreateApplication. - `application` Application, required: An application represents a client application that uses Beyond Identity for authentication. This could be a native app, a single-page application, regular web application, or machine-to-machine application credentials. - `id` string: A unique identifier for an application. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the application's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the application's tenant. This is automatically set on creation. This field is immutable and read-only. - `resource_server_id` string: A unique identifier for the application's resource server. At present, the only available resource server is for the Beyond Identity Management API. Referencing this resource server from an application will allow that application to grant access to Beyond Identity's APIs. When not present, this application may provide authentication (identity) but not authorization (access). - `authenticator_config_id` string: A unique identifier for the application's authenticator configuration. This field is unused for `oidc` and `oauth2` applications when `grant_type=client_credentials`. - `display_name` string: A human-readable name for the application. This name is used for display purposes. - `is_managed` boolean: A boolean indicating whether the application is managed by Beyond Identity. Managed applications may not be modified by the user. This is automatically set on creation. This field is immutable and read-only. - `protocol_config` union: Represents an application protocol configuration. - object: OAuth2 protocol configuration. - `type` 'oauth2', required - `allowed_scopes` string[]: Scopes to which this application can grant access. If this application references a resource server, this set of scopes must be a subset of the resource server's available scopes. If this application does not reference a resource server, then this application can only be used for authentication and thereby `scopes` must necessarily be empty. - `client_id` string: The client ID for this application. This is automatically set on creation. This field is output-only. - `client_secret` string: The client secret to authenticate as this application; typically, as a Basic Authorization header. This is automatically set on creation. This field is output-only. This field is present only when confidentiality is `confidential`. - `confidentiality` 'confidential' | 'public': The confidentiality of the client, as prescribed by OAuth 2.0 and OIDC. Confidentiality is based on a client's ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Allowable values are: - `confidential`: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means. - `public`: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post' | 'none': Indicator of the requested authentication method for the token endpoint. Allowable values are: - `client_secret_post`: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the body of the POST request. - `client_secret_basic`: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the Basic Authorization header. - `none`: The `client_secret` is not part of the request body and there is no authorization header. This endpoint authentication method is only allowed if the application has `confidentiality` set to `confidential`. Deprecation Notice: This field is deprecated. The API will ignore the value of this field in requests. In responses, confidential applications will always have `client_secret_basic` and public applications will always have `none`. On authentication, confidential applications may use both `client_secret_post` and `client_secret_basic`. Public applications may only use `none`. **This field is scheduled for removal on August 1, 2023** - `grant_type` string[]: Grant types supported by this application's `token` endpoint. Allowable values are: - `authorization_code`: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the `token` endpoint with a grant code which it obtains via the `authorize` endpoint. - `client_credentials`: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the `token` endpoint with a client credentials tuple of `client_id` and `client_secret`. - `redirect_uris` string[]: A list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information. - `token_configuration` TokenConfiguration: Properties of a token issued for an application. - `expires_after` integer, required: Time after minting, in seconds, for which the token will be considered valid. - `token_signing_algorithm` 'RS256': Signing algorithm to use for an application token. The only allowable value at present is `RS256`. - `subject_field` 'id' | 'email' | 'username': Property of a principal which is used to fill the subject of a token issued for this application. - `pkce` 'disabled' | 'plain' | 's256': 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. - `token_format` 'self_contained' | 'referential': Allowed access token formats for this application. token type. Allowable values are: - `self_contained`: token in JWT format. - `referential`: Encoded token which requires /introspect call in order to retrieve token claims. - object: OIDC protocol configuration. - `type` 'oidc', required - `allowed_scopes` string[]: Scopes to which this application can grant access. If this application references a resource server, this set of scopes must be a subset of the resource server's available scopes. If this application does not reference a resource server, then this application can only be used for authentication and thereby `scopes` must necessarily be empty. Note that OIDC requests may accept OpenID Connect standard scopes as well as resource server scopes, but the OpenID Connect scopes should not be defined on the application itself. Currently, the only OpenID Connect supported scope is `openid`. - `client_id` string: The client ID for this application. This is automatically set on creation. This field is output-only. - `client_secret` string: The client secret to authenticate as this application; typically, as a Basic Authorization header. This is automatically set on creation. This field is output-only. This field is present only when confidentiality is `confidential`. - `confidentiality` 'confidential' | 'public': The confidentiality of the client, as prescribed by OAuth 2.0 and OIDC. Confidentiality is based on a client's ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Allowable values are: - `confidential`: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means. - `public`: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post' | 'none': Indicator of the requested authentication method for the token endpoint. Allowable values are: - `client_secret_post`: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the body of the POST request. - `client_secret_basic`: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the Basic Authorization header. - `none`: The `client_secret` is not part of the request body and there is no authorization header. This endpoint authentication method is only allowed if the application has `confidentiality` set to `confidential`. Deprecation Notice: This field is deprecated. The API will ignore the value of this field in requests. In responses, confidential applications will always have `client_secret_basic` and public applications will always have `none`. On authentication, confidential applications may use both `client_secret_post` and `client_secret_basic`. Public applications may only use `none`. **This field is scheduled for removal on August 1, 2023** - `grant_type` string[]: Grant types supported by this application's `token` endpoint. Allowable values are: - `authorization_code`: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the `token` endpoint with a grant code which it obtains via the `authorize` endpoint. - `client_credentials`: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the `token` endpoint with a client credentials tuple of `client_id` and `client_secret`. - `redirect_uris` string[]: A list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information. - `token_configuration` TokenConfiguration: Properties of a token issued for an application. - `expires_after` integer, required: Time after minting, in seconds, for which the token will be considered valid. - `token_signing_algorithm` 'RS256': Signing algorithm to use for an application token. The only allowable value at present is `RS256`. - `subject_field` 'id' | 'email' | 'username': Property of a principal which is used to fill the subject of a token issued for this application. - `pkce` 'disabled' | 'plain' | 's256': 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. - `token_format` TokenFormat (unresolved $ref) - 4 (unresolved $ref) ## Response `200` The response will be a JSON object containing the standard attributes associated with an application. - Application: An application represents a client application that uses Beyond Identity for authentication. This could be a native app, a single-page application, regular web application, or machine-to-machine application credentials. - `id` string: A unique identifier for an application. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the application's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the application's tenant. This is automatically set on creation. This field is immutable and read-only. - `resource_server_id` string: A unique identifier for the application's resource server. At present, the only available resource server is for the Beyond Identity Management API. Referencing this resource server from an application will allow that application to grant access to Beyond Identity's APIs. When not present, this application may provide authentication (identity) but not authorization (access). - `authenticator_config_id` string: A unique identifier for the application's authenticator configuration. This field is unused for `oidc` and `oauth2` applications when `grant_type=client_credentials`. - `display_name` string: A human-readable name for the application. This name is used for display purposes. - `is_managed` boolean: A boolean indicating whether the application is managed by Beyond Identity. Managed applications may not be modified by the user. This is automatically set on creation. This field is immutable and read-only. - `protocol_config` union: Represents an application protocol configuration. - object: OAuth2 protocol configuration. - `type` 'oauth2', required - `allowed_scopes` string[]: Scopes to which this application can grant access. If this application references a resource server, this set of scopes must be a subset of the resource server's available scopes. If this application does not reference a resource server, then this application can only be used for authentication and thereby `scopes` must necessarily be empty. - `client_id` string: The client ID for this application. This is automatically set on creation. This field is output-only. - `client_secret` string: The client secret to authenticate as this application; typically, as a Basic Authorization header. This is automatically set on creation. This field is output-only. This field is present only when confidentiality is `confidential`. - `confidentiality` 'confidential' | 'public': The confidentiality of the client, as prescribed by OAuth 2.0 and OIDC. Confidentiality is based on a client's ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Allowable values are: - `confidential`: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means. - `public`: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post' | 'none': Indicator of the requested authentication method for the token endpoint. Allowable values are: - `client_secret_post`: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the body of the POST request. - `client_secret_basic`: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the Basic Authorization header. - `none`: The `client_secret` is not part of the request body and there is no authorization header. This endpoint authentication method is only allowed if the application has `confidentiality` set to `confidential`. Deprecation Notice: This field is deprecated. The API will ignore the value of this field in requests. In responses, confidential applications will always have `client_secret_basic` and public applications will always have `none`. On authentication, confidential applications may use both `client_secret_post` and `client_secret_basic`. Public applications may only use `none`. **This field is scheduled for removal on August 1, 2023** - `grant_type` string[]: Grant types supported by this application's `token` endpoint. Allowable values are: - `authorization_code`: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the `token` endpoint with a grant code which it obtains via the `authorize` endpoint. - `client_credentials`: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the `token` endpoint with a client credentials tuple of `client_id` and `client_secret`. - `redirect_uris` string[]: A list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information. - `token_configuration` TokenConfiguration: Properties of a token issued for an application. - `expires_after` integer, required: Time after minting, in seconds, for which the token will be considered valid. - `token_signing_algorithm` 'RS256': Signing algorithm to use for an application token. The only allowable value at present is `RS256`. - `subject_field` 'id' | 'email' | 'username': Property of a principal which is used to fill the subject of a token issued for this application. - `pkce` 'disabled' | 'plain' | 's256': 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. - `token_format` 'self_contained' | 'referential': Allowed access token formats for this application. token type. Allowable values are: - `self_contained`: token in JWT format. - `referential`: Encoded token which requires /introspect call in order to retrieve token claims. - object: OIDC protocol configuration. - `type` 'oidc', required - `allowed_scopes` string[]: Scopes to which this application can grant access. If this application references a resource server, this set of scopes must be a subset of the resource server's available scopes. If this application does not reference a resource server, then this application can only be used for authentication and thereby `scopes` must necessarily be empty. Note that OIDC requests may accept OpenID Connect standard scopes as well as resource server scopes, but the OpenID Connect scopes should not be defined on the application itself. Currently, the only OpenID Connect supported scope is `openid`. - `client_id` string: The client ID for this application. This is automatically set on creation. This field is output-only. - `client_secret` string: The client secret to authenticate as this application; typically, as a Basic Authorization header. This is automatically set on creation. This field is output-only. This field is present only when confidentiality is `confidential`. - `confidentiality` 'confidential' | 'public': The confidentiality of the client, as prescribed by OAuth 2.0 and OIDC. Confidentiality is based on a client's ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Allowable values are: - `confidential`: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means. - `public`: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means. - `token_endpoint_auth_method` 'client_secret_basic' | 'client_secret_post' | 'none': Indicator of the requested authentication method for the token endpoint. Allowable values are: - `client_secret_post`: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the body of the POST request. - `client_secret_basic`: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. Namely, `client_id` and `client_secret` are sent in the Basic Authorization header. - `none`: The `client_secret` is not part of the request body and there is no authorization header. This endpoint authentication method is only allowed if the application has `confidentiality` set to `confidential`. Deprecation Notice: This field is deprecated. The API will ignore the value of this field in requests. In responses, confidential applications will always have `client_secret_basic` and public applications will always have `none`. On authentication, confidential applications may use both `client_secret_post` and `client_secret_basic`. Public applications may only use `none`. **This field is scheduled for removal on August 1, 2023** - `grant_type` string[]: Grant types supported by this application's `token` endpoint. Allowable values are: - `authorization_code`: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the `token` endpoint with a grant code which it obtains via the `authorize` endpoint. - `client_credentials`: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the `token` endpoint with a client credentials tuple of `client_id` and `client_secret`. - `redirect_uris` string[]: A list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information. - `token_configuration` TokenConfiguration: Properties of a token issued for an application. - `expires_after` integer, required: Time after minting, in seconds, for which the token will be considered valid. - `token_signing_algorithm` 'RS256': Signing algorithm to use for an application token. The only allowable value at present is `RS256`. - `subject_field` 'id' | 'email' | 'username': Property of a principal which is used to fill the subject of a token issued for this application. - `pkce` 'disabled' | 'plain' | 's256': 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. - `token_format` TokenFormat (unresolved $ref) - 4 (unresolved $ref) ## Other responses - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: The resource was not found. - `500`: Server error. ## Changes - **2026-11-06** `42f3cac49392`: 2 info - added the new optional request property `application/protocol_config/oneOf[#/components/schemas/4]/use_short_url` - added the optional property `protocol_config/oneOf[#/components/schemas/4]/use_short_url` to the response with the `200` status [Operation history](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/changes/v1/tenants/:tenant_id/realms/:realm_id/applications/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)