Create a request

Okta Identity Governance

Create a request

Request

OAuth 2.0 scope:

okta.accessRequests.request.manage

Admin roles:

ACCESS_REQUESTS_ADMIN

Creates a resource access request for a given user.

Use this operation to create access requests managed by access request conditions.

If requestedBy and requestedFor aren't the same, then you must also enable the requestOnBehalfOfSettings parameter in the access request settings. See Update the resource request settings.

Include the following information in the payload:

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 field information in the requesterFieldValues array. See Retrieve the request fields.
Optional: The user ID of the person submitting the request. By default, this value is the admin user ID requesting this operation 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.

Bodyapplication/jsonrequired

The writable attributes of a request

requestedany(request-resource-creatable)required

requestedByobject(target-principal)

A representation of a principal

requestedForobject(target-principal)required

A representation of a principal

requesterFieldValuesArray of objects(request-field-values)

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.

POST

/governance/api/v2/requests

curl -i -X POST \
  https://okta-subdomain.pixtulate.com/governance/api/v2/requests \
  -H 'Content-Type: application/json' \
  -d '{
    "requested": {
      "type": "CATALOG_ENTRY",
      "entryId": "cen3qpimoKc7wCPyx8g6"
    },
    "requestedFor": {
      "type": "OKTA_USER",
      "externalId": "00ub0oNGTSWTBKOLGLNR"
    }
  }'

Responses

Response when create request is accepted

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

idstring, non-emptyrequired

Unique identifier for the object

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

The id of the Okta user who created the resource

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

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

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

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

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

The id of the Okta user who last updated the object

_linksobject(request-links)required

Links to related resources

statusstringrequired

The status of the request

Value:"SUBMITTED"

resolvedstring or null, (date-time)(request-resolved-date-time)

The date the request was resolved. The property may transition from having a value to null if the request is reopened.

grantStatusstring(request-grant-status)

The grant status of the request

Enum:"PENDING""GRANTED""FAILED""MANUAL_REQUIRED"

grantedstring or null, (date-time)(request-granted-date-time)

The date the approved access was granted. Only set if request.status is APPROVED.

revocationStatusstring(request-revocation-status)

The revocation status of the request

Enum:"PENDING""REVOKED""FAILED"

revokedstring or null, (date-time)(request-revoked-date-time)

The date the granted access was revoked. Only set if request.grantStatus is GRANTED and request.revocationStatus is REVOKED.

requestedByobject(client-credential-principal)required

A representation of a principal

requestedForobject(target-principal)required

A representation of a principal

requestedobject(requested)required

A representation of the resource in request

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"

revocationScheduledstring or null, (date-time)(request-revocation-scheduled-date-time)

The date the granted access is scheduled for recovation. Only set if request.accessDuration exists, and request.grantStatus is GRANTED.

requesterFieldValuesArray of objects(request-field-values)

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.

riskAssessmentobject(risk-assessment)

A risk assessment that indicates whether request submission is allowed or restricted. It contains the risk rules that lead to possible conflicts for the requested resource.

Response

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": {
    "catalogEntry": { … },
    "self": { … }
  }
}