Submit Access Request
POST/access-requests
Use this API to submit an access request in Identity Security Cloud (ISC), where it follows any ISC approval processes.
Access requests are processed asynchronously by ISC. A successful response from this endpoint means that the request has been submitted to ISC and is queued for processing. Because this endpoint is asynchronous, it doesn't return an error if you submit duplicate access requests in quick succession or submit an access request for access that is already in progress, approved, or rejected.
It's best practice to check for any existing access requests that reference the same access items before submitting a new access request. This can be accomplished by using the List Access Request Status or the Pending Access Request Approvals APIs. You can also use the Search API to check the existing access items an identity has before submitting an access request to ensure that you aren't requesting access that is already granted. If you use this API to request access that an identity already has, the API will ignore the request. These ignored requests do not display when you use the List Access Request Status API.
There are two types of access request:
GRANT_ACCESS
- Can be requested for multiple identities in a single request.
- Supports self request and request on behalf of other users. Refer to the Get Access Request Configuration endpoint for request configuration options.
- Allows any authenticated token (except API) to call this endpoint to request to grant access to themselves. Depending on the configuration, a user can request access for others.
- Roles, access profiles and entitlements can be requested.
- While requesting entitlements, maximum of 25 entitlements and 10 recipients are allowed in a request.
REVOKE_ACCESS
- Can only be requested for a single identity at a time.
- You cannot use an access request to revoke access from an identity if that access has been granted by role membership or by birthright provisioning.
- Does not support self request. Only manager can request to revoke access for their directly managed employees.
- If a
removeDate
is specified, then the access will be removed on that date and time only for roles, access profiles and entitlements. - Roles, access profiles, and entitlements can be requested for revocation.
- Revoke requests for entitlements are limited to 1 entitlement per access request currently.
- You can specify a
removeDate
if the access doesn't already have a sunset date. TheremoveDate
must be a future date, in the UTC timezone. - Allows a manager to request to revoke access for direct employees. A user with ORG_ADMIN authority can also request to revoke access from anyone.
Request
- application/json
Body
required
Array [
- Comment is required when the request is of type Revoke Access.
- Specify a date in the future.
- The current SLA for the deprovisioning is 24 hours.
- This date can be modified to either extend or decrease the duration of access item assignments for the specified identity. You can change the expiration date for requests for yourself or direct reports, but you cannot remove an expiration date on an already approved item. If the access request has not been approved, you can cancel it and submit a new one without the expiration. If it has already been approved, then you have to revoke the access and then re-request without the expiration.
]
A list of Identity IDs for whom the Access is requested. If it's a Revoke request, there can only be one Identity ID.
Possible values: [GRANT_ACCESS
, REVOKE_ACCESS
, null
]
Access request type. Defaults to GRANT_ACCESS. REVOKE_ACCESS type can only have a single Identity ID in the requestedFor field.
requestedItems
object[]
required
Possible values: >= 1
, <= 25
Possible values: [ACCESS_PROFILE
, ROLE
, ENTITLEMENT
]
The type of the item being requested.
ID of Role, Access Profile or Entitlement being requested.
Comment provided by requester.
clientMetadata
object
Arbitrary key-value pairs. They will never be processed by the IdentityNow system but will be returned on associated APIs such as /account-activities and /access-request-status.
The date the role or access profile or entitlement is no longer assigned to the specified identity. Also known as the expiration date.
clientMetadata
object
Arbitrary key-value pairs. They will never be processed by the IdentityNow system but will be returned on associated APIs such as /account-activities.
Responses
- 202
- 400
- 401
- 403
- 429
- 500
Accepted - Returned if the request was successfully accepted into the system.
- application/json
- Schema
- Example (from schema)
Schema
object
{}
Client Error - Returned if the request body is invalid.
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.
- application/json
- Schema
- Example (from schema)
Schema
A message describing the error
{
"error": "JWT validation failed: JWT is expired"
}
Forbidden - Returned if the user you are running as, doesn't have access to this end-point.
- application/json
- Schema
- Example (from schema)
- 403
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
An example of a 403 response object
{
"detailCode": "403 Forbidden",
"trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The server understood the request but refuses to authorize it."
}
]
}
Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.
- application/json
- Schema
- Example (from schema)
Schema
A message describing the error
{
"message": " Rate Limit Exceeded "
}
Internal Server Error - Returned if there is an unexpected error.
- application/json
- Schema
- Example (from schema)
- 500
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
An example of a 500 response object
{
"detailCode": "500.0 Internal Fault",
"trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "An internal fault occurred."
}
]
}