Applications

The Applications API allows you to list and manage Access Gateway applications and application-related configurations.

List all applications

Lists all applications that are configured in Access Gateway

Request

query Parameters

expand

Array of strings

Use the expand query parameter to return additional items in the _embedded object

Items Enum: "healthCheck" "behavior" "session" "resources" "policies" "attributes" "ebsAgent" "ebsClassic"

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

429

Too Many Requests

get/api/v2/apps

Request samples

Response samples

application/json

[{"id": "44931df2-4464-4c4d-97ce-5d0177b09f30",
"name": "testapp",
"type": "OAG_HEADER_BASED",
"description": "Header site",
"label": "Test App",
"idpId": "3f63f461-c7fc-483b-b2ae-961633d251ac",
"publicDomain": "oagapp.domain.tld",
"status": "CREATED",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"loadBalanced": true,
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30,
"localNetworkAccessRestriction": false,
"_embedded": {"healthCheck": {"enabled": false,
"path": "/",
"method": "GET",
"statusCode": 200,
"interval": 10,
"timeout": 1,
"healthyThreshold": 3,
"unhealthyThreshold": 3
},
"behavior": {"singleLogout": false,
"universalLogout": false,
"globalTokenRevocation": false,
"noSession": "IDP_REDIRECT",
"policyDenied": "OAG_DEFAULT_PAGE",
"sessionIntegrityFailure": "CUSTOM_URL",
"sessionIntegrityFailureUrl": "https://app.domain.tld/errorPage",
"logout": "OAG_LOGOUT_PATH",
"logoutPath": "/oagLogout",
"postLogoutUrl": "https://app.domain.tld/logout",
"error": "OAG_ERROR_PATH",
"errorPath": "/oagError",
"errorManaged": false,
"postErrorUrl": "https://app.domain.tld/error",
"login": "NO_APP_LOGIN_PATH",
"loginPath": "/login",
"loginManaged": false,
"maintenance": "CUSTOM_URL",
"maintenanceUrl": "https://app.domain.tld/maintenance",
"inactive": "CUSTOM_URL",
"inactiveUrl": "https://app.domain.tld/inactive"
},
"session": {"auth": "HEADER",
"enforceRelayState": false,
"deepLinking": true,
"idleSession": true,
"idleSessionTimeout": 3600,
"maxSession": true,
"maxSessionTimeout": 28800,
"browserSessionExpiration": false
},
"protectedResources": [{"id": "c4cadb66-68fc-49cc-8dc4-719e97bd42e1",
"hostname": "http://app1.internal.domain.tld",
"assignedWeight": 1,
"active": true,
"calculatedWeight": 1
}
],
"policies": [{"id": "9ef3103a-50a7-4517-92d6-442612b6d5c1",
"name": "root",
"description": "Protect all application resources",
"resourcePath": "/",
"active": true,
"rule": "PROTECTED",
"regexRule": null,
"caseSensitive": true,
"customDirective": null
}
],
"attributes": [{"id": "9c471061-8981-43c5-a7bc-deef2150a5a2",
"active": true,
"name": "sampleheader",
"source": "IDP",
"value": "firstName",
"type": "HEADER"
}
]
}
}
]

Create an application

Creates a new application in Access Gateway.

Newly created applications have the CREATED status. To make the application available for end users, you must configure the required settings of an application, and then activate the application.

Ensure that you've configured the following settings of your application:

Create at least one protected resource.
Create at least one policy.
Create at least one attribute (not required for OAG_NOAUTH applications).

Session, behavior and health check configurations are created by default for all applications. You can update these configurations as needed.

This endpoint also creates the default attributes and policies for the application based on the application type specified. To disable creating default attributes and policies, set the createDefaultAttributesAndPolicies parameter to false in the request body.

After creating an application, you can view the application details in the response. The _embedded property includes all the default configurations created for the application (session, behavior, health check, attributes, and policies).

Request

Request Body schema: application/json
required

type required	string Application type Enum: "OAG_HEADER_BASED" "OAG_ADMINUI" "OAG_NOAUTH" "OAG_SAMPLE_COOKIE" "OAG_SAMPLE_HEADER" "OAG_SAMLPLE_POLICY" "OAG_SAMPLE_WIKIPEDIA" "ORACLE_ACCESSGATE" "ORACLE_AGILE_PLM" "ORACLE_APPLICATION_EXPRESS" "ORACLE_DEMANTRA" "ORACLE_HCM_CLOUD" "ORACLE_HYPERION" "ORACLE_JDE" "ORACLE_OBIEE" "ORACLE_PEOPLESOFT" "ORACLE_WEBCENTER" "ORACLE_WEBLOGIC"
label required	string The name of the application, and also the tile name in your Okta tenant. The label must be unique.
publicDomain required	string <hostname> The URL of the domain that's entered by users to gain access to this application. The domain must be registered with a domain registrar.
idpId required	string <uuid> IdP identifier
certificateId required	string <uuid> Certificate identifier
postLoginUrl required	string <uri> ^https?://[a-zA-Z0-9.-]+(:[0-9]{1,5})?/?$ The default URL that end users are directed to after they sign in
loadBalanced required	boolean Default: false Indicates whether the application is load balanced. If `loadBalanced` is `true`, you can distribute the request load for an application across multiple servers.
useDefaultHeadersAndPolicies	boolean Default: true Create default attributes and policies in the application based on the application template for the provided application type. If this property is set to `false`, you must create attributes and policies manually after the application is created.
contentRewrite	boolean Indicates whether Access Gateway attempts to rewrite redirects and URLs in an app's HTML content
debug	boolean Default: false Indicates whether debug logging is enabled for the application
description	string Application description
groups	Array of strings Array of group IDs from your Okta org that are granted access to the application
hostHeaderValue	string The value of the host header that's passed to the back-end protected web resources. It uses the fully qualified external name.
localNetworkAccessRestriction	boolean Default: false Indicates whether local network access restriction is enabled. If `localNetworkAccessRestriction` is `true`, Access Gateway only allows proxy requests from local network IP addresses.
maxFileSize	integer Default: 1 Maximum file upload size allowed by the application. The default value is 1 MB. Setting it to 0 (zero) allows for an unlimited file upload size. Use this format: `1mb`.
proxyReadTimeout	integer [ 1 .. 99999999 ] Default: 60 Defines a timeout in seconds for reading a response from the proxied server. The timeout counter takes effect only between two successive read operations, not for the transmission of the whole response. If the proxied server doesn't transmit anything within this time, the connection is closed.
proxyRedirect	boolean Indicates whether the application is a proxy redirect application. If `proxyRedirect` is `true`, Access Gateway redirects the browser to the protected resource URL.
usePublicDomainAsHostHeader	boolean Indicates whether the application sends a host header to the protected resource. If it's set to `true`, Access Gateway uses the public domain name as the host header value. If it's set to `false`, Access Gateway uses the `hostHeaderValue` as the host header value if `hostHeaderValue` is specified. If it's set to `false` and `hostHeaderValue` isn't specified, Access Gateway uses the protected resource hostname as the host header value.

Responses

200

Application created successfully

400

Bad Request

401

Unauthorized

403

Forbidden

429

Too Many Requests

post/api/v2/apps

Request samples

application/json

{"type": "OAG_HEADER_BASED",
"label": "Test App",
"description": "Header site",
"idpId": "3f63f461-c7fc-483b-b2ae-961633d251ac",
"publicDomain": "oagapp.domain.tld",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"loadBalanced": true,
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30
}

Response samples

application/json

{"id": "44931df2-4464-4c4d-97ce-5d0177b09f30",
"name": "testapp",
"type": "OAG_HEADER_BASED",
"description": "Header site",
"label": "Test App",
"idpId": "3f63f461-c7fc-483b-b2ae-961633d251ac",
"publicDomain": "oagapp.domain.tld",
"status": "CREATED",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"loadBalanced": true,
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30,
"localNetworkAccessRestriction": false,
"_embedded": {"healthCheck": {"enabled": false,
"path": "/",
"method": "GET",
"statusCode": 200,
"interval": 10,
"timeout": 1,
"healthyThreshold": 3,
"unhealthyThreshold": 3
},
"behavior": {"singleLogout": false,
"universalLogout": false,
"globalTokenRevocation": false,
"noSession": "IDP_REDIRECT",
"policyDenied": "OAG_DEFAULT_PAGE",
"sessionIntegrityFailure": "CUSTOM_URL",
"sessionIntegrityFailureUrl": "https://app.domain.tld/errorPage",
"logout": "OAG_LOGOUT_PATH",
"logoutPath": "/oagLogout",
"postLogoutUrl": "https://app.domain.tld/logout",
"error": "OAG_ERROR_PATH",
"errorPath": "/oagError",
"errorManaged": false,
"postErrorUrl": "https://app.domain.tld/error",
"login": "NO_APP_LOGIN_PATH",
"loginPath": "/login",
"loginManaged": false,
"maintenance": "CUSTOM_URL",
"maintenanceUrl": "https://app.domain.tld/maintenance",
"inactive": "CUSTOM_URL",
"inactiveUrl": "https://app.domain.tld/inactive"
},
"session": {"auth": "HEADER",
"enforceRelayState": false,
"deepLinking": true,
"idleSession": true,
"idleSessionTimeout": 3600,
"maxSession": true,
"maxSessionTimeout": 28800,
"browserSessionExpiration": false
},
"protectedResources": [{"id": "c4cadb66-68fc-49cc-8dc4-719e97bd42e1",
"hostname": "http://app1.internal.domain.tld",
"assignedWeight": 1,
"active": true,
"calculatedWeight": 1
}
],
"policies": [{"id": "9ef3103a-50a7-4517-92d6-442612b6d5c1",
"name": "root",
"description": "Protect all application resources",
"resourcePath": "/",
"active": true,
"rule": "PROTECTED",
"regexRule": null,
"caseSensitive": true,
"customDirective": null
}
],
"attributes": [{"id": "9c471061-8981-43c5-a7bc-deef2150a5a2",
"active": true,
"name": "sampleheader",
"source": "IDP",
"value": "firstName",
"type": "HEADER"
}
]
}
}

Retrieve an application

Retrieves details of a specific application by applicationId

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

query Parameters

expand

Array of strings

Use the expand query parameter to return additional items in the _embedded object

Items Enum: "healthCheck" "behavior" "session" "resources" "policies" "attributes" "ebsAgent" "ebsClassic"

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v2/apps/{applicationId}

Request samples

Response samples

application/json

{"id": "44931df2-4464-4c4d-97ce-5d0177b09f30",
"name": "testapp",
"type": "OAG_HEADER_BASED",
"description": "Header site",
"label": "Test App",
"idpId": "3f63f461-c7fc-483b-b2ae-961633d251ac",
"publicDomain": "oagapp.domain.tld",
"status": "CREATED",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"loadBalanced": true,
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30,
"localNetworkAccessRestriction": false,
"_embedded": {"healthCheck": {"enabled": false,
"path": "/",
"method": "GET",
"statusCode": 200,
"interval": 10,
"timeout": 1,
"healthyThreshold": 3,
"unhealthyThreshold": 3
},
"behavior": {"singleLogout": false,
"universalLogout": false,
"globalTokenRevocation": false,
"noSession": "IDP_REDIRECT",
"policyDenied": "OAG_DEFAULT_PAGE",
"sessionIntegrityFailure": "CUSTOM_URL",
"sessionIntegrityFailureUrl": "https://app.domain.tld/errorPage",
"logout": "OAG_LOGOUT_PATH",
"logoutPath": "/oagLogout",
"postLogoutUrl": "https://app.domain.tld/logout",
"error": "OAG_ERROR_PATH",
"errorPath": "/oagError",
"errorManaged": false,
"postErrorUrl": "https://app.domain.tld/error",
"login": "NO_APP_LOGIN_PATH",
"loginPath": "/login",
"loginManaged": false,
"maintenance": "CUSTOM_URL",
"maintenanceUrl": "https://app.domain.tld/maintenance",
"inactive": "CUSTOM_URL",
"inactiveUrl": "https://app.domain.tld/inactive"
},
"session": {"auth": "HEADER",
"enforceRelayState": false,
"deepLinking": true,
"idleSession": true,
"idleSessionTimeout": 3600,
"maxSession": true,
"maxSessionTimeout": 28800,
"browserSessionExpiration": false
},
"protectedResources": [{"id": "c4cadb66-68fc-49cc-8dc4-719e97bd42e1",
"hostname": "http://app1.internal.domain.tld",
"assignedWeight": 1,
"active": true,
"calculatedWeight": 1
}
],
"policies": [{"id": "9ef3103a-50a7-4517-92d6-442612b6d5c1",
"name": "root",
"description": "Protect all application resources",
"resourcePath": "/",
"active": true,
"rule": "PROTECTED",
"regexRule": null,
"caseSensitive": true,
"customDirective": null
}
],
"attributes": [{"id": "9c471061-8981-43c5-a7bc-deef2150a5a2",
"active": true,
"name": "sampleheader",
"source": "IDP",
"value": "firstName",
"type": "HEADER"
}
]
}
}

Replace an application

Replaces an existing application configuration

Use this endpoint to update the configuration of the specified application.

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

Request Body schema: application/json
required

certificateId	string <uuid> Certificate identifier
contentRewrite	boolean Indicates whether Access Gateway attempts to rewrite redirects and URLs in an app's HTML content
debug	boolean Default: false Indicates whether debug logging is enabled for the application
description	string Application description
groups	Array of strings Array of group IDs from your Okta org that are granted access to the application
hostHeaderValue	string The value of the host header that's passed to the back-end protected web resources. It uses the fully qualified external name.
idpId	string <uuid> IdP identifier
label	string The name of the application, and also the tile name in your Okta tenant. The label must be unique.
loadBalanced	boolean Default: false Indicates whether the application is load balanced. If `loadBalanced` is `true`, you can distribute the request load for an application across multiple servers.
localNetworkAccessRestriction	boolean Default: false Indicates whether local network access restriction is enabled. If `localNetworkAccessRestriction` is `true`, Access Gateway only allows proxy requests from local network IP addresses.
maxFileSize	integer Default: 1 Maximum file upload size allowed by the application. The default value is 1 MB. Setting it to 0 (zero) allows for an unlimited file upload size. Use this format: `1mb`.
postLoginUrl	string <uri> ^https?://[a-zA-Z0-9.-]+(:[0-9]{1,5})?/?$ The default URL that end users are directed to after they sign in
proxyReadTimeout	integer [ 1 .. 99999999 ] Default: 60 Defines a timeout in seconds for reading a response from the proxied server. The timeout counter takes effect only between two successive read operations, not for the transmission of the whole response. If the proxied server doesn't transmit anything within this time, the connection is closed.
proxyRedirect	boolean Indicates whether the application is a proxy redirect application. If `proxyRedirect` is `true`, Access Gateway redirects the browser to the protected resource URL.
publicDomain	string <hostname> The URL of the domain that's entered by users to gain access to this application. The domain must be registered with a domain registrar.
type	string Application type Enum: "OAG_HEADER_BASED" "OAG_ADMINUI" "OAG_NOAUTH" "OAG_SAMPLE_COOKIE" "OAG_SAMPLE_HEADER" "OAG_SAMLPLE_POLICY" "OAG_SAMPLE_WIKIPEDIA" "ORACLE_ACCESSGATE" "ORACLE_AGILE_PLM" "ORACLE_APPLICATION_EXPRESS" "ORACLE_DEMANTRA" "ORACLE_HCM_CLOUD" "ORACLE_HYPERION" "ORACLE_JDE" "ORACLE_OBIEE" "ORACLE_PEOPLESOFT" "ORACLE_WEBCENTER" "ORACLE_WEBLOGIC"
usePublicDomainAsHostHeader	boolean Indicates whether the application sends a host header to the protected resource. If it's set to `true`, Access Gateway uses the public domain name as the host header value. If it's set to `false`, Access Gateway uses the `hostHeaderValue` as the host header value if `hostHeaderValue` is specified. If it's set to `false` and `hostHeaderValue` isn't specified, Access Gateway uses the protected resource hostname as the host header value.

Responses

200

Application updated successfully

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v2/apps/{applicationId}

Request samples

application/json

{"label": "Test App",
"description": "Header site",
"publicDomain": "oagapp.domain.tld",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30
}

Response samples

application/json

{"id": "44931df2-4464-4c4d-97ce-5d0177b09f30",
"name": "testapp",
"type": "OAG_HEADER_BASED",
"description": "Header site",
"label": "Test App",
"idpId": "3f63f461-c7fc-483b-b2ae-961633d251ac",
"publicDomain": "oagapp.domain.tld",
"status": "CREATED",
"postLoginUrl": "https://oagapp.domain.tld/landing",
"groups": ["00ghsrbfqxmSf7Ekw1d7"
],
"certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c",
"loadBalanced": true,
"usePublicDomainAsHostHeader": false,
"hostHeaderValue": "app.domain.tld",
"contentRewrite": false,
"proxyRedirect": false,
"maxFileSize": 4000,
"proxyReadTimeout": 30,
"localNetworkAccessRestriction": false
}

Delete an application

Deletes an application by applicationId.

To delete an application, you must set the status of the application to INACTIVE. Use the Deactivate an application endpoint to set the application status to INACTIVE. Deleting an application removes the application and its configurations, including its resources, policies, and attributes. These objects don't need to be deleted separately.

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

Responses

204

Application deleted successfully

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v2/apps/{applicationId}

Request samples

Response samples

application/json

{"details": { },
"errorCode": "BAD_REQUEST",
"message": "Request validation failed"
}

Activate an application

Activates a newly created application in Access Gateway. Activate an application after you create it. Access Gateway doesn't automatically activate newly created applications.

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v2/apps/{applicationId}/activate

Request samples

Response samples

application/json

{"details": { },
"errorCode": "BAD_REQUEST",
"message": "Request validation failed"
}

Deactivate an application

Deactivates an existing application in Access Gateway

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v2/apps/{applicationId}/deactivate

Request samples

Response samples

application/json

{"details": { },
"errorCode": "BAD_REQUEST",
"message": "Request validation failed"
}

Update an application status to maintenance

Updates the status of an application to maintenance mode in Access Gateway

When an application is in maintenance mode, you can perform maintenance tasks on the application. However, the application is unavailable for end users.

Request

path Parameters

applicationId

required

string <uuid>

Identifier of the application

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v2/apps/{applicationId}/maintenance

Request samples

Response samples

application/json

{"details": { },
"errorCode": "BAD_REQUEST",
"message": "Request validation failed"
}

Social
CONTACT & LEGAL
MORE INFORMATION
okta.com
Products, case studies, resources
Help Center
Knowledgebase, roadmaps, and more
Trust
System status, security, compliance

Applications

List all applications

query Parameters

Create an application

Request Body schema: application/jsonrequired

Retrieve an application

path Parameters

query Parameters

Replace an application

path Parameters

Request Body schema: application/jsonrequired

Delete an application

path Parameters

Activate an application

path Parameters

Deactivate an application

path Parameters

Update an application status to maintenance

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required