Requests

Okta Access Requests automate the process of requesting access to resources managed by access request conditions.

Access request conditions define the resource to access, who can request access, length of access, and the approval sequence. For more information, see Access request conditions. See also the following APIs: Request Conditions and Request Sequences.

Manage the access request process directly with the following request APIs.

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

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

Lists the requests made by users in your org

You can use this endpoint to retrieve all access requests managed by access request conditions.

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

  • status: The status of the request. Possible values: SUBMITTED, REJECTED, PENDING, APPROVED, DENIED, CANCELED, EXPIRED
  • 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=reqp1pmpjhVdGEcVK1d5
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
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.manage
Creates a resource access request for a given user


You can use this endpoint to create access requests managed by access request conditions.


If requestedBy and requestedFor are not the same, you must also enable the requestOnBehalfOfSettings property on the Access request settings. See Request Settings.


As part of the payload for the Create a request endpoint, include the following information:


    

  • The Okta user ID for the user who requires access. Add the user ID in the requestedFor.externalId parameter.
    • 

  • The Catalog entry ID of the resource required by the user. Add the catalog ID in the requested.entryId parameter.
    • 

  • If the request conditions include requester input fields, add the field and information for the field to the requesterFieldValues array. See Retrieve an entry's request fields.
    • 

  • Optional: The user ID of the person submitting the request. By default, this value is the admin user ID calling the endpoint and doesn't need to be provided. However, to add a different Okta user ID for the request, include the requestedBy.externalId parameter in the request body.
    • 



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",
  • "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
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.read
Retrieves the full representation of a specific request


You can use this endpoint to retrieve access requests managed by access request conditions.


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:  reqp1pmpjhVdGEcVK1d5
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",
  • "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
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.accessRequests.request.manage
Creates a message to add context to the Access requests using request conditions and sequences. The message appears in the Requester section of the Access Requests console, and the message is authored by the admin user ID calling the endpoint.


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


 
 Example:  reqp1pmpjhVdGEcVK1d5
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": [ ]
}