Requests

Okta Access Requests automate the process of requesting access to apps and resources.

Each request is associated with a request condition and sequence that determine the actions taken by Okta Access Request.

Manage this process directly with the following request APIs.

See Access Requests for more information on Access Requests and Identity Governance.

List all requests
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.read

List the requests made by users in your org.

Use the filter parameter, a SCIM query string, to narrow down the results. It supports the following attributes:

  • status: The status of the request. Possible values: SUBMITTED, REJECTED, PENDING, APPROVED, DENIED, CANCELED
  • lastUpdated: The last updated time of the request
  • requestedFor: The Okta user ID for whom the request is made
  • resourceId: The Okta resource ID for which the request is made
  • resourceType: The type of resource for which the request is made. Possible values: APPLICATION
  • accessScopeId: The ID of the resource access scope for which the request is made
  • accessScopeType: The type of the resource access scope for which the request is made. Possible values: ENTITLEMENT_BUNDLE, GROUP, APPLICATION

Pagination parameters are accepted, and standard link headers are in the response.

Request
query Parameters
after
string <rcar-request-id> = 20 characters

The after cursor provided by a prior request.

Example: after=reqb0oNGTSWTBKOLGLNR
filter
string <scim-filter>

Apply various filters by using supported request filtering properties.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:
Query param: ?filter=status eq "APPROVED"
filter=status%20eq%20%22APPROVED%22
Query param: ?filter=lastUpdated gt "2022-05-24T14:15:22Z"
filter=lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=resourceId eq "0oafxqCAJWWGELFTYASJ"
filter=resourceId%20eq%20%220oafxqCAJWWGELFTYASJ%22
Query param: ?filter=resourceType eq "APPLICATION"
filter=resourceType%20eq%20%22APPLICATION%22
Query param: ?filter=accessScopeId eq "0oafxqCAJWWGELFTYASJ"
filter=resourceId%20eq%20%220oafxqCAJWWGELFTYASJ%22
Query param: ?filter=accessScopeType eq "APPLICATION"
filter=accessScopeType%20eq%20%22APPLICATION%22
Query param: ?filter=requestedFor eq "00ub0oNGTSWTBKOLGLNR"
filter=requestedFor%20eq%20%2200ub0oNGTSWTBKOLGLNR%22
Query param: ?filter=status eq "RESOLVED" AND resourceId eq "0oafxqCAJWWGELFTYASJ"
filter=status%20eq%20%22RESOLVED%22%20AND%20resourceId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20
limit
integer [ 1 .. 200 ]
Default: 20

The maximum number of records that will be returned in a given result.

orderBy
string <order-by>

Apply an ordering of requests by specifying a supported request property name with %20asc or %20desc suffix.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:
Query param: ?orderBy=created desc
orderBy=created%20desc
Query param: ?orderBy=lastUpdated desc
orderBy=lastUpdated%20desc
Responses
200

A successful request list response

400

An invalid request to list requests

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

get/governance/api/v2/requests
Request samples 
Response samples 
application/json
A list request response with no filter


{}
Create a request
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.manage
Creates a resource access request for a given user.


In general, the following information is needed to create a request:


    

  • Who is creating the request?
    • 

  • For whom is this access request? 
    • 

  • Which resource is the access request about?
    • 

  • What is the approval process for this request?
    • 

  • What information is to be submitted with this request?
    • 



Request 
Request Body schema: application/json
required
The writable attributes of a request


required
any
A representation of a resource that can be requested for access. 


Note: The resources available for the request are subject to their permission settings. For example, the Okta Admin App 
can only be requested by Super Admin users. 


 
required
object
A representation of a principal


 
object
A representation of a principal


 
Array of objects
The requester input fields required by the approval system.


Note: The fields required are determined by the approval system.


For the Okta approval system, the required fields are defined in the approval sequence. Ensure that the requester
input fields match up with this definition to avoid request approval flow failure.


For external approval systems, the requester input fields are for recording purposes only and do not affect the approval
process.


 
Responses 
202
Response when create request is accepted


400
An invalid request to create a request


401
When authentication fails


403
When authorization fails


409
A conflict with the request type prevents the create request operation


500
When there is a server fault due to an unexpected error


post/governance/api/v2/requests
Request samples 
application/json
When requested.type is CATALOG_ENTRY, requestApproval.type is OKTA with no requester input fields


{
  • "requested": {
    • "type": "CATALOG_ENTRY",
    • "entryId": "cen3qpimoKc7wCPyx8g6"
    },
  • "requestedFor": {
    • "type": "OKTA_USER",
    • "externalId": "00ub0oNGTSWTBKOLGLNR"
    }
}
Response samples 
application/json
Request access for authenticated user by omitting requesterUserIds


{
  • "id": "req42kjDgk1EubTwo0g4",
  • "subject": "request-from-service-now-xsd23432",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-05T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "SUBMITTED",
  • "requestedBy": {
    • "type": "OKTA_USER",
    • "externalId": "00ub0oNGTSWTBKOLGLNR"
    },
  • "requestedFor": {
    • "type": "OKTA_USER",
    • "externalId": "00ub0oNGTSWTBKOLGLNR"
    },
  • "requested": {
    • "entryId": "cenb0oADRXTBKOLGLNR",
    • "resourceId": "0oafxqCAJWWGELFTYASJ",
    • "resourceType": "APPLICATION",
    • "accessScopeType": "APPLICATION",
    • "accessScopeId": "0oafxqCAJWWGELFTYASJ"
    },
  • "_links": {}
}
Retrieve a request
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.read
Retrieves the full representation of a specific request.


More information is returned than the abbreviated representation in a List requests operation.


Request 
path Parameters
requestId
required
string <rcar-request-id>   = 20 characters 
The id of the request


 
 Example:  reqb0oNGTSWTBKOLGLNR
Responses 
200
A successful get request response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


get/governance/api/v2/requests/{requestId}
Request samples 
Response samples 
application/json
Submitted requests can't yet have an approvalSequenceId or requestConditionId.


{
  • "id": "req42kjDgk1EubTwo0g4",
  • "subject": "request-from-service-now-xsd23432",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-05T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "SUBMITTED",
  • "requestedBy": {
    • "type": "OKTA_USER",
    • "externalId": "00ub0oNGTSWTBKOLGLNR"
    },
  • "requestedFor": {
    • "type": "OKTA_USER",
    • "externalId": "00ub0oNGTSWTBKOLGLNR"
    },
  • "requesterFieldValues": [
    • {
      • "id": "05c87fe9-11f6-4d40-a033-b155b39dcdbe",
      • "label": "What is the business justification for the request?",
      • "type": "TEXT",
      • "value": "I need access to complete a task."
      }
    ],
  • "requested": {
    • "entryId": "cenb0oADRXTBKOLGLNR",
    • "resourceId": "0oafxqCAJWWGELFTYASJ",
    • "resourceType": "APPLICATION",
    • "accessScopeId": "0oafxqCAJWWGELFTYASJ",
    • "accessScopeType": "APPLICATION"
    },
  • "_links": {}
}
Create a request message
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.manage
Creates a message to add context to the request. Message will be authored by the authenticated user and display as "Sent via API".


Request 
path Parameters
requestId
required
string <rcar-request-id>   = 20 characters 
The id of the request


 
 Example:  reqb0oNGTSWTBKOLGLNR
Request Body schema: application/json
required
The writable attributes of a request message


message
required
string  [ 1 .. 5000 ] characters 
Message that will be created for the request. Newline can be specified by characters "\n". Message will be visible for all users who can view the request.


 
Responses 
201
A successful create request message response


401
When authentication fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


post/governance/api/v2/requests/{requestId}/messages
Request samples 
application/json
Add request message for authenticated user visible to all


{
  • "message": "Contact admin@atko.com for any additional assistance needed with this request."
}
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}