Request Types

The Request Types API allows you to manage request types, similar to the operations performed in the Okta Access Requests app. Use this API to define request types that include:

  • Fields to complete
  • Approvals and tasks required
  • Actions performed in Okta

See Access Request Types in the product documentation.

Notes:

  • Each org has a limit of 500 active request types.
  • Operations to create or delete apps or groups in Okta could take up to 24 hours before they can be referenced by the Access Requests - V1 APIs. To trigger these changes 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
OAuth 2.0 scope:
  • okta.governance.accessRequests.manage
Admin roles:
  • ACCESS_REQUESTS_ADMIN

Creates a request type that governs the requests allowed in your org.

Specify the following to create a request type:

  • 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)

Notes:

  • You can have a maximum of 100 combined items across approvalSettings.approvals, approvalSettings.approvals.approverFields, and requestSettings.requesterFields objects for each request type. This translates to a maximum of 100 combined questions, tasks, or actions for each request type.
  • The limit on the JSON response payload of a request type is 100,000 characters.
Request
Request Body schema: application/json
required

The writable attributes of a request type

required
object

Specify one of the following type of approval settings:

Type Description
NONE This request type doesn't need any approval.
SERIAL This request type needs at least one approval.
name
required
string [ 1 .. 50 ] characters

A user-defined unique key that's set during the create operation and can't be updated afterwards

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 scope:
  • 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 returned in a response

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 wasn't 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
OAuth 2.0 scope: 
  • okta.governance.accessRequests.read
Admin roles: 
  • ACCESS_REQUESTS_ADMIN
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 wasn't 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
OAuth 2.0 scope: 
  • okta.governance.accessRequests.manage
Admin roles: 
  • ACCESS_REQUESTS_ADMIN
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 wasn't 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
OAuth 2.0 scope: 
  • okta.governance.accessRequests.manage
Admin roles: 
  • ACCESS_REQUESTS_ADMIN
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 wasn't 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
OAuth 2.0 scope: 
  • okta.governance.accessRequests.manage
Admin roles: 
  • ACCESS_REQUESTS_ADMIN
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 wasn't 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
OAuth 2.0 scope: 
  • okta.governance.accessRequests.read
Admin roles: 
  • ACCESS_REQUESTS_ADMIN
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 returned in a response


 
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"
      }
    ]
}