Skip to main content

applications

Creates, updates, deletes, gets or lists an applications resource.

Overview​

Nameapplications
TypeResource
Idokta.apps.applications

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
idstringUnique ID for the app instance
_embeddedobjectEmbedded resources related to the app using the JSON Hypertext Application Language specification. If the expand=user/{userId} query parameter is specified, then the assigned Application User is embedded.
_linksobjectDiscoverable resources related to the app
accessibilityobjectSpecifies access settings for the app
createdstring (date-time)Timestamp when the application object was created
featuresarrayEnabled app features > Note: See Application Features for app provisioning features.
labelstringUser-defined display name for app
lastUpdatedstring (date-time)Timestamp when the application object was last updated
licensingobjectLicenses for the app
ornstringThe Okta resource name (ORN) for the current app instance
profileobjectContains 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.
signOnModestringAuthentication 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:
statusstringApp instance status
universalLogoutobject<div class="x-lifecycle-container"><x-lifecycle class="oie"></x-lifecycle></div> Universal Logout properties for the app. These properties are only returned and can't be updated. (example: ACTIVE)
visibilityobjectSpecifies visibility settings for the app

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
list_applicationsselectsubdomainq, after, useOptimization, limit, filter, expand, includeNonDeletedLists 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]https://developer.okta.com/docs/api#pagination 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).

> Note: To list all of a member's assigned app links, use the List all assigned app links endpoint in the User Resources API.
get_applicationselectsubdomainexpandRetrieves an application from your Okta organization by id
create_applicationinsertsubdomain, data__signOnMode, data__labelactivate, OktaAccessGateway-AgentCreates 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.
replace_applicationreplacesubdomain, data__signOnMode, data__labelReplaces 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.
delete_applicationdeletesubdomainDeletes an inactive application
activate_applicationexecsubdomainActivates an inactive application
deactivate_applicationexecsubdomainDeactivates an active application

> Note: Deactivating an app triggers a full reconciliation of all users assigned to the app by groups. This reconcile process removes the app assignment for the deactivated app, and might also correct assignments that were supposed to be removed but failed previously.
upload_application_logoexecsubdomain, fileUploads a logo for the app instance.
If the app already has a logo, this operation replaces the previous logo.

The logo is visible in the Admin Console as an icon for your app instance.
If you have one appLink object configured, this logo also appears in the End-User Dashboard as an icon for your app.
> Note: If you have multiple appLink objects, use the Admin Console to add logos for each app link.
> You can't use the API to add logos for multiple app links.
assign_application_policyexecsubdomainAssigns an app to an authentication policy, identified by policyId.
If the app was previously assigned to another policy, this operation replaces that assignment with the updated policy identified by policyId.

> Note: When you merge duplicate authentication policies,
the policy and mapping CRUD operations may be unavailable during the consolidation. When the consolidation is complete, you receive an email with merged results.
preview_samlmetadata_for_applicationexeckid, subdomainPreviews the SSO SAML metadata for an application

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
kidstring
subdomainstringThe domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)
OktaAccessGateway-Agentstring
activatebooleanExecutes activation lifecycle operation when creating the app
afterstringSpecifies the [pagination]https://developer.okta.com/docs/api#pagination cursor for the next page of results. Treat this as an opaque value obtained through the next link relationship.
expandstringAn optional query parameter to return the specified Application User in the _embedded property. Valid value: expand=user/&#123;userId&#125;
filterstringFilters apps by status, user.id, group.id, credentials.signing.kid or name expression that supports the eq operator
includeNonDeletedbooleanSpecifies whether to include non-active, but not deleted apps in the results
limitinteger (int32)Specifies the number of results per page
qstringSearches for apps with name or label properties that starts with the q value using the startsWith operation
useOptimizationbooleanSpecifies whether to use query optimization. If you specify useOptimization=true in the request query, the response contains a subset of app instance properties.

SELECT examples​

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]https://developer.okta.com/docs/api#pagination 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).

> Note: To list all of a member's assigned app links, use the List all assigned app links endpoint in the User Resources API.

SELECT
id,
_embedded,
_links,
accessibility,
created,
features,
label,
lastUpdated,
licensing,
orn,
profile,
signOnMode,
status,
universalLogout,
visibility
FROM okta.apps.applications
WHERE subdomain = '{{ subdomain }}' -- required
AND q = '{{ q }}'
AND after = '{{ after }}'
AND useOptimization = '{{ useOptimization }}'
AND limit = '{{ limit }}'
AND filter = '{{ filter }}'
AND expand = '{{ expand }}'
AND includeNonDeleted = '{{ includeNonDeleted }}';

INSERT examples​

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.

INSERT INTO okta.apps.applications (
data__accessibility,
data__label,
data__licensing,
data__profile,
data__signOnMode,
data__visibility,
subdomain,
activate,
OktaAccessGateway-Agent
)
SELECT 
'{{ accessibility }}',
'{{ label }}' --required,
'{{ licensing }}',
'{{ profile }}',
'{{ signOnMode }}' --required,
'{{ visibility }}',
'{{ subdomain }}',
'{{ activate }}',
'{{ OktaAccessGateway-Agent }}'
RETURNING
id,
_embedded,
_links,
accessibility,
created,
features,
label,
lastUpdated,
licensing,
orn,
profile,
signOnMode,
status,
universalLogout,
visibility
;

REPLACE examples​

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.

REPLACE okta.apps.applications
SET 
data__accessibility = '{{ accessibility }}',
data__label = '{{ label }}',
data__licensing = '{{ licensing }}',
data__profile = '{{ profile }}',
data__signOnMode = '{{ signOnMode }}',
data__visibility = '{{ visibility }}'
WHERE 
subdomain = '{{ subdomain }}' --required
AND data__signOnMode = '{{ signOnMode }}' --required
AND data__label = '{{ label }}' --required
RETURNING
id,
_embedded,
_links,
accessibility,
created,
features,
label,
lastUpdated,
licensing,
orn,
profile,
signOnMode,
status,
universalLogout,
visibility;

DELETE examples​

Deletes an inactive application

DELETE FROM okta.apps.applications
WHERE subdomain = '{{ subdomain }}' --required;

Lifecycle Methods​

Activates an inactive application

EXEC okta.apps.applications.activate_application 
@subdomain='{{ subdomain }}' --required;