Requests

Okta Access Requests automate the process of requesting access to resources like apps, groups, and entitlement bundles. Each request is associated with a request approval process that determines the actions taken by Okta Access Requests. 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.governance.accessRequests.read

Lists all or a subset of requests made by users in your organization.

Use the ?filter= parameter to narrow results with the following request properties: requestStatus and lastUpdated.

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

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

The after cursor provided by a prior request.

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=requestStatus eq "RESOLVED"
filter=requestStatus%20eq%20%22RESOLVED%22
Query param: ?filter=lastUpdated gt "2022-05-24T14:15:22Z"
filter=lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=requestStatus eq "RESOLVED" AND lastUpdated gt "2022-05-24T14:15:22Z"
filter=requestStatus%20eq%20%22RESOLVED%22%20AND%20lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22
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/v1/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.governance.accessRequests.manage
Creates a request to access a resource in your organization.


When creating a request, you specify:


    

  • the request type (requestTypeId) to use for the request
    • 

  • and the subject line (subject) of the request
    • 



Optionally, you can specify:


    

  • The requester user IDs for the request. If not provided, user IDs are obtained from the user identity of the API Token or Access Token.
    • 



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


requestTypeId
required
string <request-type-id>   = 24 characters 
The request type id.


 
subject
required
string  [ 1 .. 250 ] characters 
The subject of the request


 
Array of objects
Field values provided when adding the request.


If a request type has required requesterFields, they must be provided when the request is created.


Non-required fields may be omitted when creating the request.


 
requesterUserIds
Array of strings <okta-user-id>   = 1 items 
A list of requester Okta user ids.


 
Responses 
201
A successful create request response


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/v1/requests
Request samples 
application/json
Request access for authenticated user by omitting requesterUserIds


{
  • "requestTypeId": "08ab2db568c7c300079fefd0",
  • "subject": "I need access to Salesforce"
}
Response samples 
application/json
Request access for authenticated user by omitting requesterUserIds


{
  • "id": "61eb06a3c462d20007f0235c",
  • "subject": "Tom requests access to Salesforce",
  • "requestTypeId": "08ab2db568c7c300079fefd0",
  • "created": "2022-05-05T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-05T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "resolved": null,
  • "requestStatus": "OPEN",
  • "requesterUserIds": [
    • "00ub0oNGTSWTBKOLGLNR"
    ],
  • "requesterFieldValues": null,
  • "approvals": [
    • {
      • "status": "PENDING",
      • "approvalId": "62f6d63a1764a30007763ad5"
      },
    • {
      • "status": "PENDING",
      • "approvalId": "62f6d63a1764a30007763ae2"
      }
    ],
  • "actions": [
    • {
      • "status": "PENDING",
      • "action": "ASSIGN_APP_TO_USER",
      • "actionId": "62f57938cd367b0008eb47c7"
      }
    ],
  • "type": "ACCESS_REQUEST",
  • "_links": {}
}
Retrieve a request
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.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 <request-id>   = 24 characters 
The id of the request


 
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/v1/requests/{requestId}
Request samples 
Response samples 
application/json
Success response to get a Request


{
  • "id": "61eb06a3c462d20007f0235c",
  • "subject": "request-from-service-now-xsd23432",
  • "requestTypeId": "61eb2db568c7c300079fefd0",
  • "created": "2022-05-05T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-05T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "resolved": "2022-05-05T14:15:22Z",
  • "requestStatus": "RESOLVED",
  • "requesterUserIds": [
    • "00ub0oNGTSWTBKOLGLNR"
    ],
  • "requesterFieldValues": [
    • {
      • "id": "05c87fe9-11f6-4d40-a033-b155b39dcdbe",
      • "prompt": "What is the business justification for the request?",
      • "type": "TEXT",
      • "value": "I need access to complete a task.",
      • "required": true
      }
    ],
  • "approvals": [
    • {
      • "status": "COMPLETED",
      • "approvalId": "62f6d63a1764a30007763ae2",
      • "approverId": "00ub0oNGTSWTBKOLGLNR",
      • "approverName": "Becky Raferty",
      • "decision": "APPROVED",
      • "decided": "2022-06-02T21:36:25.344Z",
      • "fieldValues": [
        ]
      }
    ],
  • "actions": [
    • {
      • "status": "COMPLETED",
      • "action": "ASSIGN_APP_TO_USER",
      • "actionId": "62f6d63a1764a30007763ad5",
      • "actionStatus": "SUCCEEDED",
      • "actionAttempted": "2022-06-02T21:36:25.344Z",
      • "resourceId": "0oafxqCAJWWGELFTYASJ",
      • "resourceName": "Salesforce 01",
      • "resourceType": "APP"
      }
    ],
  • "type": "ACCESS_REQUEST",
  • "_links": {}
}
Create a Message for a Request
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.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 <request-id>   = 24 characters 
The id of the request


 
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/v1/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": [ ]
}