POST /api/v1/apps

Creates an app instance in your Okta org.

You can either create an OIN app instance or a custom app instance:

OIN app instances have prescribed name (key app definition) and signOnMode options. See the OIN schemas for the request body.
For custom app instances, select the signOnMode that pertains to your app and specify the required parameters in the request body.

Servers

https://{yourOktaDomain}

Request headers

Name	Type	Required	Description
`OktaAccessGateway-Agent`	String	No
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name Type Required Description

Name	Type	Required	Description
`activate`	Boolean	No	Executes activation lifecycle operation when creating the app Default value: true

activate

Boolean

Executes activation lifecycle operation when creating the app

Default value: true

Request body fields

Name Type Required Description

orn

String

The Okta resource name (ORN) for the current app instance

_embedded

Object

Embedded resources related to the app using the JSON Hypertext Application Language specification. If the expand=user/{userId} query parameter is specified, then the assigned Application User is embedded.

_embedded.user

Object

The specified Application User assigned to the app

signOnMode

String

Yes

Authentication mode for the app

signOnMode	Description
AUTO_LOGIN	Secure Web Authentication (SWA)
BASIC_AUTH	HTTP Basic Authentication with Okta Browser Plugin
BOOKMARK	Just a bookmark (no-authentication)
BROWSER_PLUGIN	Secure Web Authentication (SWA) with Okta Browser Plugin
OPENID_CONNECT	Federated Authentication with OpenID Connect (OIDC)
SAML_1_1	Federated Authentication with SAML 1.1 WebSSO (not supported for custom apps)
SAML_2_0	Federated Authentication with SAML 2.0 WebSSO
SECURE_PASSWORD_STORE	Secure Web Authentication (SWA) with POST (plugin not required)
WS_FEDERATION	Federated Authentication with WS-Federation Passive Requestor Profile

Select the signOnMode for your custom app:

Possible values:

"SAML_1_1"
"BASIC_AUTH"
"OPENID_CONNECT"
"WS_FEDERATION"
"SECURE_PASSWORD_STORE"
"BOOKMARK"
"BROWSER_PLUGIN"
"AUTO_LOGIN"
"SAML_2_0"

accessibility

Object

Specifies access settings for the app

accessibility.selfService

Boolean

Represents whether the app can be self-assignable by users

accessibility.loginRedirectUrl

String

Custom login page URL for the app

Note: The loginRedirectUrl property is deprecated in Identity Engine. This property is used with the custom app login feature. Orgs that actively use this feature can continue to do so. See Okta-hosted sign-in (redirect authentication) or configure IdP routing rules to redirect users to the appropriate sign-in app for orgs that don't use the custom app login feature.

accessibility.errorRedirectUrl

String

Custom error page URL for the app

status

String

App instance status

Possible values:

"DELETED"
"ACTIVE"
"INACTIVE"

lastUpdated

String

Timestamp when the Application object was last updated

id

String

Unique ID for the app instance

profile

Object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps). For example, add an app manager contact email address or define an allowlist of groups that you can then reference using the Okta Expression Language getFilteredGroups function.

Notes:

profile isn't encrypted, so don't store sensitive data in it.
profile doesn't limit the level of nesting in the JSON schema you created, but there is a practical size limit. Okta recommends a JSON schema size of 1 MB or less for best performance.

_links

Discoverable resources related to the app

visibility

Object

Specifies visibility settings for the app

visibility.autoSubmitToolbar

Boolean

Automatically sign in when user lands on the sign-in page

visibility.autoLaunch

Boolean

Automatically signs in to the app when user signs into Okta

visibility.appLinks

Object

Links or icons that appear on the End-User Dashboard if they're set to true.

visibility.hide

Object

Hides the app for specific end-user apps

visibility.hide.iOS

Boolean

Okta Mobile for iOS or Android (pre-dates Android)

Default value: false

visibility.hide.web

Boolean

Okta End-User Dashboard on a web browser

Default value: false

created

String

Timestamp when the Application object was created

licensing

Object

Licenses for the app

licensing.seatCount

Integer

Number of licenses purchased for the app

label

String

Yes

User-defined display name for app

features[]

Array

Enabled app features

Note: Some apps can support optional provisioning features. See Application Features

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.