Request Types

Request types define the operations performed by Okta Access Requests, including:

  • Fields that are completed
  • Approvals and tasks required
  • Actions performed in Okta

Manage request types with the following request type APIs.

See Access Request Types for more information on Access Request Types and Identity Governance.

Note: Operations to create or delete applications or groups in Okta could take up to 24 hours before they can be referenced by the Access Requests API. To trigger these changes in Access Requests immediately, open Okta Access Requests as an administrator, go to Settings > Configuration and click Sync Now on the relevant Okta resource list.

Create a request type
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.manage

Creates a request type, which governs whether requests are allowed and who is associated with the request.

When creating a request type, you specify:

  • What resource access can be requested
  • Who can request access
  • What question(s) requesters must answer (optional)
  • Who can approve access
  • What question(s) approvers must answer (optional)
  • How long access should be granted for (optional)
Request
Request Body schema: application/json
required

The writable attributes of a request type

required
object

There are two approvalSettings types. NONE: this request type doesn't need any approval. SERIAL: this request type needs at least one approval.

name
required
string [ 1 .. 50 ] characters

Writable unique key on Create. Not modifiable on update.

ownerId
required
string <owner-id> = 24 characters

The ID of the team that administers this request type.

required
object

Which resource(s) are requestable

accessDuration
string or null <iso-duration>
Default: null

How long the requester retains access after their request is approved and fulfilled.

Specified in ISO 8601 duration format.

Known limitation

Only single time unit ISO 8601 duration formats (D, H, M) are supported, for units (days, hours, minutes).

Supported
Unit Example
D, days P40D
H, hours PT65H
M, minutes PT90M

Note: Mixes of units, as well as month/year/week designations, are not supported. For example, P40DT65H, P40M, P1W and P1Y are not supported.

description
string [ 1 .. 2000 ] characters

Human readable description.

object
Default: {"type":"EVERYONE","requesterFields":[]}

The requestSettings control:

  • Which users can request access using this request type.
  • What fields the user may or must fill out in order to request access.
status
string
Default: "DRAFT"

Whether the request type starts with a status of DRAFT or ACTIVE. Starting as ACTIVE is preferable to avoid a publish operation when no manual inspection of the request type is necessary before publication.

Enum: "ACTIVE" "DRAFT"
Responses
201

A successful request type create response

400

An invalid request to create a request type

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

post/governance/api/v1/request-types
Request samples
application/json

The minimal set of properties to pass when creating a Request Type. Allows anyone to request access to the Admin Group. No questions are required, and there is only one approval required by the requesting user's manager.

{
  • "name": "salesforce-01",
  • "description": "How users can request access to Admin Group",
  • "ownerId": "61eb0f06c462d20007f051ac",
  • "resourceSettings": {
    • "type": "GROUPS",
    • "targetResources": [
      • {
        }
      ]
    },
  • "approvalSettings": {
    • "type": "SERIAL",
    • "approvals": [
      • {
        }
      ]
    }
}
Response samples
application/json

The minimal set of properties to pass when creating a Request Type. Allows anyone to request access to the Admin Group. No questions are required, and there is only one approval required by the requesting user's manager.

{}

List all request types
Beta
OAuth 2.0: okta.governance.accessRequests.read

Lists all or a subset of request types in your organization.

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

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

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

The after cursor provided by a prior request.

filter
string <scim-filter>

Apply various filters by using supported request types filtering properties.

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

Examples:
Query param: ?filter=status eq "ACTIVE"
filter=status%20eq%20%22ACTIVE%22
Query param: ?filter=lastUpdated gt "2022-05-24T14:15:22Z"
filter=lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=status eq "ACTIVE" AND lastUpdated gt "2022-05-24T14:15:22Z"
filter=status%20eq%20%22ACTIVE%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 request types by specifying a supported request type 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 type list response

400

An invalid request to list request types

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/request-types
Request samples 
Response samples 
application/json
A list of request type with no filter


{}
Retrieve a request type
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.read
Retrieves the full representation of a specific request type.


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


Request 
path Parameters
requestTypeId
required
string <request-type-id>   = 24 characters 
The id of the request type


 
Responses 
200
A successful request type get 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/request-types/{requestTypeId}
Request samples 
Response samples 
application/json
When getting a request type in published status


{}
Delete a request type
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.manage
Deletes a request type from your organization.


A deleted request type:


    

  • Can no longer be used to add requests
    • 

  • Can no longer be unpublished or published
    • 

  • Is no longer available for Get or List operations
    • 





Note: In-flight requests using the DELETED request type continue in their lifecycle operations using the state of the request type at the time the request was made.




Request 
path Parameters
requestTypeId
required
string <request-type-id>   = 24 characters 
The id of the request type


 
Responses 
204
A successful request type delete 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


delete/governance/api/v1/request-types/{requestTypeId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}
Publish a request type
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.manage
Publishes a request type to your organziation.


A published request type:


    

  • Can be used to create requests
    • 

  • Can be viewed by non-administrative users
    • 

  • Sets the request type's status to ACTIVE
    • 



A request type with a status of ACTIVE can be unpublished or deleted at any time.


Request 
path Parameters
requestTypeId
required
string <request-type-id>   = 24 characters 
The id of the request type


 
Responses 
200
A successful request type publish response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
An invalid request to publish a request type


429
When the rate limit has been exceeded


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


post/governance/api/v1/request-types/{requestTypeId}/publish
Request samples 
Response samples 
application/json
When getting a request type in published status


{}
Unpublish a request type
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.manage
Unpublishes a request type, which returns the status of the request type to DRAFT.


An unpublished Request Type:


    

  • Can't be used to add new requests
    • 

  • Is not visible to non-administrative users
    • 





Note: In-flight requests continue in their lifecycle using the request type definition from the point in time the request was created.




A request type with a status of DRAFT can be published or deleted at any time.


Request 
path Parameters
requestTypeId
required
string <request-type-id>   = 24 characters 
The id of the request type


 
Responses 
200
A successful request type unpublish response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
An invalid request due to status conflict when unpublishing a request type


429
When the rate limit has been exceeded


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


post/governance/api/v1/request-types/{requestTypeId}/un-publish
Request samples 
Response samples 
application/json
When getting a request type in draft status


{
  • "id": "61eb2db568c7c300079fefd0",
  • "name": "salesforce-01",
  • "description": "How users can request access to Salesforce 01",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "DRAFT",
  • "ownerId": "61eb0f06c462d20007f051ac",
  • "resourceSettings": {
    • "type": "GROUPS",
    • "targetResources": [
      • {
        }
      ]
    },
  • "requestSettings": {
    • "type": "EVERYONE",
    • "requesterFields": [
      • {
        }
      ]
    },
  • "approvalSettings": {
    • "type": "SERIAL",
    • "approvals": [
      • {
        }
      ]
    },
  • "lastUpdateSource": "API",
  • "accessDuration": null,
  • "_links": {}
}
List all teams
Beta
Admin permissions required: Access Requests Administrator
OAuth 2.0: okta.governance.accessRequests.read
Lists all or a subset of teams in your organization.


Use the ?filter= parameter to narrow results with the request type property name. This query is useful for specifying the ownerId of a request type.


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


Request 
query Parameters
after
string <owner-id>   = 24 characters 
The after cursor provided by a prior request.


 
filter
string <scim-filter> 
Apply various filters by using supported team filtering properties.


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


  Examples: 
Query param: ?filter=name eq "Salesforce admins" 
filter=name%20eq%20%22Salesforce%20admins%22
limit
integer  [ 1 .. 200 ] 
 Default:  20
The maximum number of records that will be returned in a given result.


 
Responses 
200
A successful teams list response


400
An invalid request to list teams


401
When authentication fails


403
When authorization fails


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


get/governance/api/v1/teams
Request samples 
Response samples 
application/json
A list of teams


{
  • "data": [
    • {
      • "id": "08ab2db568c7c300079fefd0",
      • "name": "Salesforce admins",
      • "created": "2022-05-24T14:15:22Z",
      • "lastUpdated": "2022-05-24T14:15:22Z"
      },
    • {
      • "id": "08ab2db568c7c300079fefd0",
      • "name": "Netsuite admins",
      • "created": "2022-05-24T14:15:22Z",
      • "lastUpdated": "2022-05-24T14:15:22Z"
      }
    ]
}