Request Types

Okta Identity Governance

Management APIs

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 750 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 admin, go to Settings > Configuration and click Sync Now on the relevant Okta resource list.

Operations

Create a request type

Request

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.

Bodyapplication/jsonrequired

The writable attributes of a request type

namestring, [ 1 .. 50 ] charactersrequired

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

Example:"salesforce-01"

descriptionstring, [ 1 .. 2000 ] characters

Human readable description

Example:"How users can request access to Salesforce 01"

statusstring(request-type-creatable-status)

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.

Default:"DRAFT"

Enum:"DRAFT""ACTIVE"

ownerIdstring, (owner-id), = 24 characters(request-type-owner-id)^[a-fA-F\d]{24}$required

The ID of the team that administers this request type.

Example:"61eb0f06c462d20007f051ac"

resourceSettingsobject(request-type-resource-settings-mutable)required

Example:

{
  "type": "GROUPS",
  "targetResources": [
    "00g1emaKYZTWRYYRRTSK"
  ]
}

requestSettingsobject(request-type-request-settings-mutable)

Example:

{
  "type": "EVERYONE",
  "requesterFields": [
    { … }
  ]
}

approvalSettingsobject(request-type-approval-settings-mutable)required

Example:

{
  "type": "SERIAL",
  "approvals": [
    { … }
  ]
}

accessDurationstring or null, (iso-duration)(request-duration)

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, aren't supported. For example, P40DT65H, P40M, P1W, and P1Y aren't supported.

Default:null

Example:"P40D"

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.

curl -i -X POST \
  https://subdomain-okta.login.adsbillinghub.com/governance/api/v1/request-types \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "salesforce-01",
    "description": "How users can request access to Admin Group",
    "ownerId": "61eb0f06c462d20007f051ac",
    "resourceSettings": {
      "type": "GROUPS",
      "targetResources": [
        {
          "resourceId": "00g1emaKYZTWRYYRRTSK"
        }
      ]
    },
    "approvalSettings": {
      "type": "SERIAL",
      "approvals": [
        {
          "approverType": "MANAGER"
        }
      ]
    }
  }'

Responses

A successful request type create response

Headers

X-Rate-Limit-Limitinteger, >= 1required

The rate-limit ceiling for the current request

Example:60

X-Rate-Limit-Remaininginteger, >= 0required

The number of requests left for the current rate-limit window

Example:60

X-Rate-Limit-Resetinteger, >= 0required

The time when the rate limit resets, specified in UTC epoch time (in seconds)

Example:1609459200

Bodyapplication/json

namestring, [ 1 .. 50 ] charactersrequired

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

Example:"salesforce-01"

descriptionstring, [ 1 .. 2000 ] charactersrequired

Human readable description

Example:"How users can request access to Salesforce 01"

idstring, non-emptyrequired

Unique identifier for the object

Example:"61eb2db568c7c300079fefd0"

createdBystring, (okta-user-id), [ 1 .. 20 ] characters(created-by)read-onlyrequired

The id of the Okta user who created the resource

Example:"00ub0oNGTSWTBKOLGLNR"

createdstring, (date-time)(created)read-onlyrequired

The ISO 8601 formatted date and time when the resource was created

Example:"2022-05-24T14:15:22Z"

lastUpdatedstring, (date-time)(last-updated)read-onlyrequired

The ISO 8601 formatted date and time when the object was last updated

Example:"2022-05-24T14:15:22Z"

lastUpdatedBystring, (okta-user-id), [ 1 .. 20 ] characters(last-updated-by)read-onlyrequired

The id of the Okta user who last updated the object

Example:"00ub0oNGTSWTBKOLGLNR"

_linksobject(request-type-links)required

Links to related resources

Example:

{
  "createRequest": {
    "href": "https://my-org.at-okta.login.adsbillinghub.com/next/new?q=Request%20access%20to%20Salesforce&request_type=0oa1gjh63g214q0Hq0g4",
    "type": "text/html"
  },
  "requests": {
    "href": "https://myorg-okta.login.adsbillinghub.com/governance/api/v1/requests?filter=requestTypeId%20eq%20%2261eb2db568c7c300079fefd0%22",
    "type": "application/json"
  },
  "self": {
    "href": "https://myorg-okta.login.adsbillinghub.com/governance/api/v1/requests/61eb2db568c7c300079fefd0",
    "type": "application/json"
  }
}

ownerIdstring, (owner-id), = 24 characters(request-type-owner-id)^[a-fA-F\d]{24}$required

The ID of the team that administers this request type.

Example:"61eb0f06c462d20007f051ac"

resourceSettingsobject(request-type-resource-settings-readable)required

Example:

{
  "type": "GROUPS",
  "targetResources": [
    "00g1emaKYZTWRYYRRTSK"
  ]
}

requestSettingsobject(request-type-request-settings-readable)required

Example:

{
  "type": "EVERYONE",
  "requesterFields": [
    { … }
  ]
}

approvalSettingsobject(request-type-approval-settings-readable)required

Example:

{
  "type": "SERIAL",
  "approvals": [
    { … }
  ]
}

accessDurationstring or null, (iso-duration)(request-duration)required

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, aren't supported. For example, P40DT65H, P40M, P1W, and P1Y aren't supported.

Default:null

Example:"P40D"

statusstring(request-type-status)required

A request type has a status lifecycle described in our request type lifecycle documentation.

A request type may start with a status of DRAFT or ACTIVE, based on the status property in the Add request body.

The publish, unpublish, and delete operations all affect a request type's status.

Additionally, if any operation detects invalid settings, such as an approver who is no longer in the organization, the request type automatically transitions to disabled.

Enum:"DRAFT""ACTIVE""DISABLED"

Example:"ACTIVE"

lastUpdateSourcestring(request-type-last-update-source)required

Whether the request type was last updated through the API or the user interface.

Enum:"API""WEB"

Example:"API"

Response

{
  "id": "08ab2db568c7c300079fefd0",
  "name": "low-privilege-group-01-request-type-02",
  "description": "How users can request access to low privilege Group 01",
  "created": "2022-05-24T14:15:22Z",
  "createdBy": "00ub0oNGTSWTBKOLGLNR",
  "lastUpdated": "2022-05-24T14:15:22Z",
  "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  "status": "DRAFT",
  "lastUpdateSource": "API",
  "ownerId": "61eb0f06c462d20007f051ac",
  "resourceSettings": {
    "type": "GROUPS",
    "targetResources": [ … ]
  },
  "requestSettings": {
    "type": "EVERYONE",
    "requesterFields": []
  },
  "approvalSettings": {
    "type": "SERIAL",
    "approvals": [ … ]
  },
  "accessDuration": null,
  "_links": {
    "createRequest": { … },
    "requests": { … },
    "self": { … }
  }
}