Applications

The Applications API provides operations to manage apps in your org.

To create a custom app integration instance, use the Create an Application operation with the schema provided in the request payload.

To create an app instance from the Okta Integration Network (OIN), use the Create an Application operation with the corresponding OIN app schema in the request body.

Google Workspace

Schema for the Google Workspace app (key name: google)

To create a Google Workspace app, use the Create an Application request with the following parameters in the request body.

Note: The Google Workspace app only supports BROWSER_PLUGIN and SAML_2_0 sign-on modes.

name
required
string

The key name for the OIN app definition

Value: "google"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (GoogleApplicationSettings)

App settings

required
object (GoogleApplicationSettingsApplication)

Google app instance properties

domain
required
string

Your Google company domain

rpId
string

RPID

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Enum: "BROWSER_PLUGIN" "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "google",
  • "label": "Sample Google App",
  • "signOnMode": "SAML_2_0",
  • "settings": {
    • "app": {
      }
    }
}

Microsoft Office 365

Schema for the Microsoft Office 365 app (key name: office365)

To create a Microsoft Office 365 app, use the Create an Application request with the following parameters in the request body.

Note: The Office 365 app only supports BROWSER_PLUGIN and SAML_1_1 sign-on modes.

name
required
string

The key name for the OIN app definition

Value: "office365"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (Office365ApplicationSettings)

App settings

required
object (Office365ApplicationSettingsApplication)

Office365 app instance properties

msftTenant
required
string

Microsoft tenant name

domain
required
string

The domain for your Office 365 account

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 1.1 settings)

Contains SAML 1.1 sign-on mode attributes

audienceOverride
string

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string

Identifies a specific application resource in an IdP-initiated SSO scenario

recipientOverride
string

Recipient override for CASB configuration. See CASB config guide.

ssoAcsUrlOverride
string

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Enum: "BROWSER_PLUGIN" "SAML_1_1"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "office365",
  • "label": "Sample Office365 App",
  • "signOnMode": "SAML_1_1",
  • "settings": {
    • "app": {
      }
    }
}

Org2Org

Schema for the Okta Org2Org app (key name: okta_org2org)

To create an Org2Org app, use the Create an Application request with the following parameters in the request body.

Notes:

  • The Okta Org2Org (okta_org2org) app isn't available in Okta Developer Edition orgs. If you need to test this feature in your Developer Edition org, contact your Okta account team.
  • The Okta Org2Org app supports SAML_2_0 and AUTO_LOGIN sign-on modes.
name
required
string

The key name for the OIN app definition

Value: "okta_org2org"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (Org2OrgApplicationSettings)

App settings

required
object (Org2OrgApplicationSettingsApplication)

Org2Org app instance properties

baseUrl
required
string

The base URL of the target Okta org (for SAML_2_0 sign-on mode)

acsUrl
string

The Assertion Consumer Service (ACS) URL of the source org (for SAML_2_0 sign-on mode)

audRestriction
string

The entity ID of the SP (for SAML_2_0 sign-on mode)

creationState
string

Used to track and manage the state of the app's creation or the provisioning process between two Okta orgs

preferUsernameOverEmail
boolean

Indicates that you don't want to use an email address as the username

token
string

An API token from the target org that's used to secure the connection between the orgs

tokenEncrypted
string

Encrypted token to enhance security

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string
Default: "SAML_2_0"

Authentication mode for the app

Enum: Description
SAML_2_0

Federated Authentication with SAML 2.0 WebSSO

AUTO_LOGIN

Secure Web Authentication (SWA)

status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{}

Salesforce

Schema for the Salesforce app (key name: salesforce)

To create a Salesforce app, use the Create an Application request with the following parameters in the request body.

Note: The Salesforce app only supports BROWSER_PLUGIN, BOOKMARK, and SAML_2_0 sign-on modes.

name
required
string

The key name for the OIN app definition

Value: "salesforce"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (SalesforceApplicationSettings)

App settings

required
object (SalesforceApplicationSettingsApplication)

Salesforce app instance properties

integrationType
required
string

Salesforce integration type

Enum: "STANDARD" "PORTAL" "COMMUNITY"
instanceType
required
string

Salesforce instance that you want to connect to

Enum: "SANDBOX" "PRODUCTION" "GOVERNMENT"
loginUrl
string

The Login URL specified in your Salesforce Single Sign-On settings

logoutUrl
string

Salesforce Logout URL

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Enum: "BROWSER_PLUGIN" "BOOKMARK" "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "salesforce",
  • "label": "Sample Salesforce App",
  • "signOnMode": "SAML_2_0",
  • "settings": {
    • "app": {
      }
    }
}

Slack

Schema for the Slack app (key name: slack)

To create a Slack app, use the Create an Application request with the following parameters in the request body.

Note: The Slack app only supports BROWSER_PLUGIN and SAML_2_0 sign-on modes.

name
required
string

The key name for the OIN app definition

Value: "slack"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (SlackApplicationSettings)

App settings

required
object (SlackApplicationSettingsApplication)

Slack app instance properties

domain
required
string

The Slack app domain name

userEmailValue
string

The User.Email attribute value

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Enum: "BROWSER_PLUGIN" "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "slack",
  • "label": "Sample Slack App",
  • "signOnMode": "SAML_2_0",
  • "settings": {
    • "app": {
      }
    }
}

Trend Micro Apex One Service

Schema for Trend Micro Apex One as a Service app (key name: trendmicroapexoneservice)

To create a Trend Micro Apex One as a Service app, use the Create an Application request with the following parameters in the request body.

Note: The Trend Micro Apex One as a Service app only supports SAML_2_0 sign-on mode.

name
required
string

The key name for the OIN app definition

Value: "trendmicroapexoneservice"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (TrendMicroApexOneServiceApplicationSettings)

App settings

required
object (TrendMicroApexOneServiceApplicationSettingsApplication)

Trend Micro Apex One as a Service app instance properties

baseURL
required
string

Base Trend Micro Apex One Service URL

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Value: "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "trendmicroapexoneservice",
  • "label": "Sample Trend Micro Apex One as a Service App",
  • "signOnMode": "SAML_2_0",
  • "settings": {}
}

Zoom

Schema for the Zoom app (key name: zoomus)

To create a Zoom app, use the Create an Application request with the following parameters in the request body.

Note: The Zoom app only supports SAML_2_0 sign-on mode.

name
required
string

The key name for the OIN app definition

Value: "zoomus"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (ZoomUsApplicationSettings)

App settings

required
object (ZoomUsApplicationSettingsApplication)

Zoom app instance properties

subDomain
required
string

Your Zoom subdomain

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Value: "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "zoomus",
  • "label": "Sample Zoom App",
  • "signOnMode": "SAML_2_0",
  • "settings": {
    • "app": {
      }
    }
}

Zscaler 2.0

Schema for the Zscaler 2.0 app (key name: zscalerbyz)

To create a Zscaler 2.0 app, use the Create an Application request with the following parameters in the request body.

Note: The Zscaler 2.0 app only supports BROWSER_PLUGIN and SAML_2_0 sign-on modes.

name
required
string

The key name for the OIN app definition

Value: "zscalerbyz"
label
required
string (ApplicationLabel)

User-defined display name for app

required
object (ZscalerbyzApplicationSettings)

App settings

required
object (ZscalerbyzApplicationSettingsApplication)

Zscaler app instance properties

siteDomain
string

Your Zscaler domain

identityStoreId
string

Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.

implicitAssignment
boolean

Controls whether Okta automatically assigns users to the app based on the user's role or group membership.

inlineHookId
string

Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.

object (ApplicationSettingsNotes)

App notes visible to either the admin or end user

admin
string

An app message that's visible to admins

enduser
string

A message that's visible in the End-User Dashboard

object (ApplicationSettingsNotifications)

Specifies notifications settings for the app

object (ApplicationSettingsNotificationsVpn)

Sends customizable messages with conditions to end users when a VPN connection is required

object (SAML 2.0 settings)

Contains SAML 2.0 sign-on mode attributes.

Note: Set destinationOverride to configure any other SAML 2.0 attributes in this section.

Array of objects (SamlAttributeStatement)

A list of custom attribute statements for the app's SAML assertion. See SAML 2.0 Technical Overview.

There are two types of attribute statements:

Type Description
EXPRESSION Generic attribute statement that can be dynamic and supports Okta Expression Language
GROUP Group attribute statement
audienceOverride
string or null

Audience override for CASB configuration. See CASB config guide.

defaultRelayState
string or null

Identifies a specific application resource in an IdP-initiated SSO scenario

destinationOverride
string or null

Destination override for CASB configuration. See CASB config guide.

recipientOverride
string or null

Recipient override for CASB configuration. See CASB config guide.

samlAssertionLifetimeSeconds
integer

Determines the SAML app session lifetimes with Okta

ssoAcsUrlOverride
string or null

Assertion Consumer Service (ACS) URL override for CASB configuration. See CASB config guide.

object (ApplicationAccessibility)

Specifies access settings for the app

errorRedirectUrl
string

Custom error page URL for the app

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.

selfService
boolean

Represents whether the app can be self-assignable by users

object (SchemeApplicationCredentials)

Credentials for the specified signOnMode

object

App signing key properties

Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.

kid
string

Key identifier used for signing assertions

Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.

lastRotated
string <date-time>

Timestamp when the signing key was last rotated

nextRotation
string <date-time>

The scheduled time for the next signing key rotation

rotationMode
string

The mode of key rotation

use
string

Specifies the intended use of the key

Value: "sig"
object (ApplicationCredentialsUsernameTemplate)

The template used to generate the username when the app is assigned through a group or directly to a user

pushStatus
string

Determines if the username is pushed to the app on updates for CUSTOM type

Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"
template
string
Default: "${source.login}"

Mapping expression used to generate usernames.

The following are supported mapping expressions that are used with the BUILT_IN template type:

Name Template Expression
AD Employee ID ${source.employeeID}
AD SAM Account Name ${source.samAccountName}
AD SAM Account Name (lowercase) ${fn:toLowerCase(source.samAccountName)}
AD User Principal Name ${source.userName}
AD User Principal Name prefix ${fn:substringBefore(source.userName, "@")}
Email ${source.email}
Email (lowercase) ${fn:toLowerCase(source.email)}
Email prefix ${fn:substringBefore(source.email, "@")}
LDAP UID + custom suffix ${source.userName}${instance.userSuffix}
Okta username ${source.login}
Okta username prefix ${fn:substringBefore(source.login, "@")}
type
string
Default: "BUILT_IN"

Type of mapping expression. Empty string is allowed.

Enum: "NONE" "BUILT_IN" "CUSTOM"
userSuffix
string

An optional suffix appended to usernames for BUILT_IN mapping expressions

object (PasswordCredential)

Specifies a password for a user.

When a user has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).

For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a password object when creating or updating a user, but not for other operations. See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revealPassword
boolean

Allow users to securely see their password

scheme
string (ApplicationCredentialsScheme)

Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.

Enum: Description
ADMIN_SETS_CREDENTIALS

Admin sets username and password

EDIT_PASSWORD_ONLY

Admin sets username, user sets password

EDIT_USERNAME_AND_PASSWORD

User sets username and password

EXTERNAL_PASSWORD_SYNC

Admin sets username, password is the same as user's Okta password

SHARED_USERNAME_AND_PASSWORD

Users share a single username and password set by the admin

userName
string [ 1 .. 100 ] characters

Shared username for the app

object (ApplicationLicensing)

Licenses for the app

seatCount
integer

Number of licenses purchased for the app

object

Contains any valid JSON schema for specifying properties that can be referenced from a request (only available to OAuth 2.0 client apps)

property name*
additional property
object
signOnMode
string

Authentication mode for the app

Enum: "BROWSER_PLUGIN" "SAML_2_0"
status
string (ApplicationLifecycleStatus)

App instance status

Enum: "ACTIVE" "DELETED" "INACTIVE"
object (ApplicationVisibility)

Specifies visibility settings for the app

object

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

property name*
additional property
boolean
autoLaunch
boolean

Automatically signs in to the app when user signs into Okta

autoSubmitToolbar
boolean

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

object (ApplicationVisibilityHide)

Hides the app for specific end-user apps

iOS
boolean
Default: false

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

web
boolean
Default: false

Okta End-User Dashboard on a web browser

{
  • "name": "zscalerbyz",
  • "label": "Sample Zscaler 2.0 App",
  • "signOnMode": "SAML_2_0"
}

List all applications
OAuth 2.0:
  • okta.apps.read

Lists all apps in the org with pagination. A subset of apps can be returned that match a supported filter expression or query. The results are paginated according to the limit parameter. If there are multiple pages of results, the header contains a next link. Treat the link as an opaque value (follow it, don't parse it).

Request
query Parameters
q
string

Searches for apps with name or label properties that starts with the q value using the startsWith operation

Example: q=Okta
after
string

Specifies the pagination cursor for the next page of results. Treat this as an opaque value obtained through the next link relationship.

Example: after=16278919418571
useOptimization
boolean
Default: false

Specifies whether to use query optimization. If you specify useOptimization=true in the request query, the response contains a subset of app instance properties.

limit
integer <int32> <= 200
Default: -1

Specifies the number of results per page

filter
string

Filters apps by status, user.id, group.id, credentials.signing.kid or name expression that supports the eq operator

Examples:
filter=status eq "ACTIVE"
filter=name eq "okta_org2org"
filter=credentials.signing.kid eq "SIMcCQNY3uwXoW3y0vf6VxiBb5n9pf8L2fK8d-F1bm4"
expand
string

An optional parameter used for link expansion to embed more resources in the response. Only supports expand=user/{userId} and must be used with the user.id eq "{userId}" filter query for the same user. Returns the assigned application user in the _embedded property.

Example: expand=user/0oa1gjh63g214q0Hq0g4
includeNonDeleted
boolean
Default: false

Specifies whether to include non-active, but not deleted apps in the results

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/apps
Request samples 
Response samples 
application/json
[]
Create an application
OAuth 2.0: 
  • okta.apps.manage
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.
    • 



Request 
query Parameters
activate
boolean
 Default:  true
Executes activation lifecycle operation when creating the app


 
header Parameters
OktaAccessGateway-Agent
string
 
Request Body schema: application/json
required
signOnMode
required
string (ApplicationSignOnMode) 
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:


 
label
required
string (ApplicationLabel) 
User-defined display name for app


 
object (ApplicationAccessibility) 
Specifies access settings for the app


 
errorRedirectUrl
string
Custom error page URL for the app


 
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.




 
selfService
boolean
Represents whether the app can be self-assignable by users


 
object (ApplicationLicensing) 
Licenses for the app


 
seatCount
integer
Number of licenses purchased for the app


 
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.
    • 





 
property name*
additional property
any
 
object (ApplicationVisibility) 
Specifies visibility settings for the app


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


 
property name*
additional property
boolean
 
autoLaunch
boolean
Automatically signs in to the app when user signs into Okta


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


 
object (ApplicationVisibilityHide) 
Hides the app for specific end-user apps


 
iOS
boolean
 Default:  false
Okta Mobile for iOS or Android (pre-dates Android)


 
web
boolean
 Default:  false
Okta End-User Dashboard on a web browser


 
object (SchemeApplicationCredentials) 
Credentials for the specified signOnMode


 
object
App signing key properties




Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.




 
kid
string
Key identifier used for signing assertions




Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.




 
rotationMode
string
The mode of key rotation


 
use
string
Specifies the intended use of the key


 Value: "sig"  
object (ApplicationCredentialsUsernameTemplate) 
The template used to generate the username when the app is assigned through a group or directly to a user


 
pushStatus
string
Determines if the username is pushed to the app on updates for CUSTOM type


 Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"  
template
string
 Default:  "${source.login}"
Mapping expression used to generate usernames.


The following are supported mapping expressions that are used with the BUILT_IN template type:






Name
Template Expression





AD Employee ID
${source.employeeID}




AD SAM Account Name
${source.samAccountName}




AD SAM Account Name (lowercase)
${fn:toLowerCase(source.samAccountName)}




AD User Principal Name
${source.userName}




AD User Principal Name prefix
${fn:substringBefore(source.userName, "@")}




Email
${source.email}




Email (lowercase)
${fn:toLowerCase(source.email)}




Email prefix
${fn:substringBefore(source.email, "@")}




LDAP UID + custom suffix
${source.userName}${instance.userSuffix}




Okta username
${source.login}




Okta username prefix
${fn:substringBefore(source.login, "@")}





 
type
string
 Default:  "BUILT_IN"
Type of mapping expression. Empty string is allowed.


 Enum: "NONE" "BUILT_IN" "CUSTOM"  
userSuffix
string
An optional suffix appended to usernames for BUILT_IN mapping expressions


 
object (PasswordCredential) 
Specifies a password for a user.


When a user has a valid password, imported hashed password, or password hook, and a response object contains
a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator:  Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).


For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.


 
object (PasswordCredentialHash) 
Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly
from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import.
 A hashed password may be specified in a password object when creating or updating a user, but not for other operations.
 See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.


 
object (PasswordCredentialHook) 
Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
revealPassword
boolean
Allow users to securely see their password


 
scheme
string (ApplicationCredentialsScheme) 
Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.


 Enum: Description
ADMIN_SETS_CREDENTIALS
Admin sets username and password


EDIT_PASSWORD_ONLY
Admin sets username, user sets password


EDIT_USERNAME_AND_PASSWORD
User sets username and password


EXTERNAL_PASSWORD_SYNC
Admin sets username, password is the same as user's Okta password


SHARED_USERNAME_AND_PASSWORD
Users share a single username and password set by the admin


 
userName
string  [ 1 .. 100 ] characters 
Shared username for the app


 
object (AutoLoginApplicationSettings) 
App settings


 
identityStoreId
string
Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.


 
implicitAssignment
boolean
Controls whether Okta automatically assigns users to the app based on the user's role or group membership.


 
inlineHookId
string
Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.


 
object (ApplicationSettingsNotes) 
App notes visible to either the admin or end user


 
admin
string
An app message that's visible to admins


 
enduser
string
A message that's visible in the End-User Dashboard


 
object (ApplicationSettingsNotifications) 
Specifies notifications settings for the app


 
object (ApplicationSettingsNotificationsVpn) 
Sends customizable messages with conditions to end users when a VPN connection is required


 
object (AutoLoginApplicationSettingsSignOn) 
 
loginUrl
required
string
Primary URL of the sign-in page for this app


 
redirectUrl
string
Secondary URL of the sign-in page for this app


 
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/apps
Request samples 
application/json
{}
Response samples 
application/json
{}
Retrieve an application
OAuth 2.0: 
  • okta.apps.read
Retrieves an application from your Okta organization by id


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
query Parameters
expand
string
An optional query parameter to return the specified Application User in the _embedded property.
Valid value: expand=user/{userId}


 
 Example:  expand=user/0oa1gjh63g214q0Hq0g4
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/apps/{appId}
Request samples 
Response samples 
application/json
{}
Replace an application
OAuth 2.0: 
  • okta.apps.manage
Replaces properties for an application




Notes:


    

  • All required properties must be specified in the request body
    • 

  • You can't modify system-assigned properties, such as id, name, status, created, and lastUpdated. The values for these properties in the PUT request body are ignored.
    • 





Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Request Body schema: application/json
required
signOnMode
required
string (ApplicationSignOnMode) 
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:


 
label
required
string (ApplicationLabel) 
User-defined display name for app


 
object (ApplicationAccessibility) 
Specifies access settings for the app


 
errorRedirectUrl
string
Custom error page URL for the app


 
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.




 
selfService
boolean
Represents whether the app can be self-assignable by users


 
object (ApplicationLicensing) 
Licenses for the app


 
seatCount
integer
Number of licenses purchased for the app


 
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.
    • 





 
property name*
additional property
any
 
object (ApplicationVisibility) 
Specifies visibility settings for the app


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


 
property name*
additional property
boolean
 
autoLaunch
boolean
Automatically signs in to the app when user signs into Okta


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


 
object (ApplicationVisibilityHide) 
Hides the app for specific end-user apps


 
iOS
boolean
 Default:  false
Okta Mobile for iOS or Android (pre-dates Android)


 
web
boolean
 Default:  false
Okta End-User Dashboard on a web browser


 
object (SchemeApplicationCredentials) 
Credentials for the specified signOnMode


 
object
App signing key properties




Note: Only apps with SAML_2_0, SAML_1_1, WS_FEDERATION, or OPENID_CONNECT signOnMode support the key rotation feature.




 
kid
string
Key identifier used for signing assertions




Note: Currently, only the X.509 JWK format is supported for apps with SAML_2_0 signOnMode.




 
rotationMode
string
The mode of key rotation


 
use
string
Specifies the intended use of the key


 Value: "sig"  
object (ApplicationCredentialsUsernameTemplate) 
The template used to generate the username when the app is assigned through a group or directly to a user


 
pushStatus
string
Determines if the username is pushed to the app on updates for CUSTOM type


 Enum: "PUSH" "DONT_PUSH" "NOT_CONFIGURED"  
template
string
 Default:  "${source.login}"
Mapping expression used to generate usernames.


The following are supported mapping expressions that are used with the BUILT_IN template type:






Name
Template Expression





AD Employee ID
${source.employeeID}




AD SAM Account Name
${source.samAccountName}




AD SAM Account Name (lowercase)
${fn:toLowerCase(source.samAccountName)}




AD User Principal Name
${source.userName}




AD User Principal Name prefix
${fn:substringBefore(source.userName, "@")}




Email
${source.email}




Email (lowercase)
${fn:toLowerCase(source.email)}




Email prefix
${fn:substringBefore(source.email, "@")}




LDAP UID + custom suffix
${source.userName}${instance.userSuffix}




Okta username
${source.login}




Okta username prefix
${fn:substringBefore(source.login, "@")}





 
type
string
 Default:  "BUILT_IN"
Type of mapping expression. Empty string is allowed.


 Enum: "NONE" "BUILT_IN" "CUSTOM"  
userSuffix
string
An optional suffix appended to usernames for BUILT_IN mapping expressions


 
object (PasswordCredential) 
Specifies a password for a user.


When a user has a valid password, imported hashed password, or password hook, and a response object contains
a password credential, then the password object is a bare object without the value property defined (for example, password: {}). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator:  Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password).


For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.


 
object (PasswordCredentialHash) 
Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly
from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import.
 A hashed password may be specified in a password object when creating or updating a user, but not for other operations.
 See the Create user with imported hashed password description. When you update a user with a hashed password, the user must be in the STAGED status.


 
object (PasswordCredentialHook) 
Specify a password import inline hook to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
revealPassword
boolean
Allow users to securely see their password


 
scheme
string (ApplicationCredentialsScheme) 
Apps with BASIC_AUTH, BROWSER_PLUGIN, or SECURE_PASSWORD_STORE sign-on modes have credentials vaulted by Okta and can be configured with the following schemes.


 Enum: Description
ADMIN_SETS_CREDENTIALS
Admin sets username and password


EDIT_PASSWORD_ONLY
Admin sets username, user sets password


EDIT_USERNAME_AND_PASSWORD
User sets username and password


EXTERNAL_PASSWORD_SYNC
Admin sets username, password is the same as user's Okta password


SHARED_USERNAME_AND_PASSWORD
Users share a single username and password set by the admin


 
userName
string  [ 1 .. 100 ] characters 
Shared username for the app


 
object (AutoLoginApplicationSettings) 
App settings


 
identityStoreId
string
Identifies an additional identity store app, if your app supports it. The identityStoreId value must be a valid identity store app ID. This identity store app must be created in the same org as your app.


 
implicitAssignment
boolean
Controls whether Okta automatically assigns users to the app based on the user's role or group membership.


 
inlineHookId
string
Identifier of an inline hook. Inline hooks are outbound calls from Okta to your own custom code, triggered at specific points in Okta process flows. They allow you to integrate custom functionality into those flows. See Inline hooks.


 
object (ApplicationSettingsNotes) 
App notes visible to either the admin or end user


 
admin
string
An app message that's visible to admins


 
enduser
string
A message that's visible in the End-User Dashboard


 
object (ApplicationSettingsNotifications) 
Specifies notifications settings for the app


 
object (ApplicationSettingsNotificationsVpn) 
Sends customizable messages with conditions to end users when a VPN connection is required


 
object (AutoLoginApplicationSettingsSignOn) 
 
loginUrl
required
string
Primary URL of the sign-in page for this app


 
redirectUrl
string
Secondary URL of the sign-in page for this app


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/apps/{appId}
Request samples 
application/json
{
  • "name": "bookmark",
  • "label": "Sample Bookmark App updated",
  • "signOnMode": "BOOKMARK",
  • "settings": {}
}
Response samples 
application/json
{}
Delete an application
OAuth 2.0: 
  • okta.apps.manage
Deletes an inactive application


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/apps/{appId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Activate an application
OAuth 2.0: 
  • okta.apps.manage
Activates an inactive application


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/apps/{appId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Deactivate an application
OAuth 2.0: 
  • okta.apps.manage
Deactivates an active application


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/apps/{appId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}