AccessRequests
Use this API to implement and customize access request functionality. With this functionality in place, users can request access to applications, entitlements, or roles, and managers can request that team members' access be revoked. This allows users to get access to the tools they need quickly and securely, and it allows managers to take away access to those tools.
Identity Security Cloud's Access Request service allows end users to request access that requires approval before it can be granted to users and enables qualified users to review those requests and approve or deny them.
In the Request Center in Identity Security Cloud, users can view available applications, roles, and entitlements and request access to them. If the requested tools requires approval, the requests appear as 'Pending' under the My Requests tab until the required approver approves, rejects, or cancels them.
Users can use My Requests to track and/or cancel the requests.
In My Team on the Identity Security Cloud Home, managers can submit requests to revoke their team members' access. They can use the My Requests tab under Request Center to track and/or cancel the requests.
Refer to Requesting Access for more information about access requests.
All URIs are relative to https://sailpoint.api.identitynow.com/v3
Method | HTTP request | Description |
---|---|---|
Suspend-AccessRequest | POST /access-requests/cancel | Cancel Access Request |
New-AccessRequest | POST /access-requests | Submit Access Request |
Get-AccessRequestConfig | GET /access-request-config | Get Access Request Configuration |
Get-AccessRequestStatus | GET /access-request-status | Access Request Status |
Set-AccessRequestConfig | PUT /access-request-config | Update Access Request Configuration |
cancel-access-request
This API endpoint cancels a pending access request. An access request can be cancelled only if it has not passed the approval step. In addition to users with ORG_ADMIN, any user who originally submitted the access request may cancel it.
Parameters
Param Type | Name | Data Type | Required | Description |
---|---|---|---|---|
Body | CancelAccessRequest | CancelAccessRequest | True |
Return type
Responses
Code | Description | Data Type |
---|---|---|
202 | Accepted - Returned if the request was successfully accepted into the system. | SystemCollectionsHashtable |
400 | Client Error - Returned if the request body is invalid. | ErrorResponseDto |
401 | Unauthorized - Returned if there is no authorization header, or if the JWT token is expired. | ListAccessProfiles401Response |
403 | Forbidden - Returned if the user you are running as, doesn't have access to this end-point. | ErrorResponseDto |
404 | Not Found - returned if the request URL refers to a resource or object that does not exist | ErrorResponseDto |
429 | 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. | ListAccessProfiles429Response |
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto |
HTTP request headers
- Content-Type: application/json
- Accept: application/json
Example
$CancelAccessRequest = @"{
"accountActivityId" : "2c9180835d2e5168015d32f890ca1581",
"comment" : "I requested this role by mistake."
}"@
# Cancel Access Request
try {
$Result = ConvertFrom-JsonToCancelAccessRequest -Json $CancelAccessRequest
Suspend-AccessRequest -CancelAccessRequest $Result
# Below is a request that includes all optional parameters
# Suspend-AccessRequest -CancelAccessRequest $Result
} catch {
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Suspend-AccessRequest"
Write-Host $_.ErrorDetails
}
create-access-request
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.
Parameters
Param Type | Name | Data Type | Required | Description |
---|---|---|---|---|
Body | AccessRequest | AccessRequest | True |
Return type
Responses
Code | Description | Data Type |
---|---|---|
202 | Access Request Response. | AccessRequestResponse |
400 | Client Error - Returned if the request body is invalid. | ErrorResponseDto |
401 | Unauthorized - Returned if there is no authorization header, or if the JWT token is expired. | ListAccessProfiles401Response |
403 | Forbidden - Returned if the user you are running as, doesn't have access to this end-point. | ErrorResponseDto |
429 | 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. | ListAccessProfiles429Response |
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto |
HTTP request headers
- Content-Type: application/json
- Accept: application/json
Example
$AccessRequest = @"{
"requestedFor" : [ "2c918084660f45d6016617daa9210584", "2c918084660f45d6016617daa9210584" ],
"clientMetadata" : {
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1",
"requestedAppName" : "test-app"
},
"requestType" : "GRANT_ACCESS",
"requestedItems" : [ {
"clientMetadata" : {
"requestedAppName" : "test-app",
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1"
},
"removeDate" : "2020-07-11T21:23:15Z",
"comment" : "Requesting access profile for John Doe",
"id" : "2c9180835d2e5168015d32f890ca1581",
"type" : "ACCESS_PROFILE"
}, {
"clientMetadata" : {
"requestedAppName" : "test-app",
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1"
},
"removeDate" : "2020-07-11T21:23:15Z",
"comment" : "Requesting access profile for John Doe",
"id" : "2c9180835d2e5168015d32f890ca1581",
"type" : "ACCESS_PROFILE"
}, {
"clientMetadata" : {
"requestedAppName" : "test-app",
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1"
},
"removeDate" : "2020-07-11T21:23:15Z",
"comment" : "Requesting access profile for John Doe",
"id" : "2c9180835d2e5168015d32f890ca1581",
"type" : "ACCESS_PROFILE"
}, {
"clientMetadata" : {
"requestedAppName" : "test-app",
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1"
},
"removeDate" : "2020-07-11T21:23:15Z",
"comment" : "Requesting access profile for John Doe",
"id" : "2c9180835d2e5168015d32f890ca1581",
"type" : "ACCESS_PROFILE"
}, {
"clientMetadata" : {
"requestedAppName" : "test-app",
"requestedAppId" : "2c91808f7892918f0178b78da4a305a1"
},
"removeDate" : "2020-07-11T21:23:15Z",
"comment" : "Requesting access profile for John Doe",
"id" : "2c9180835d2e5168015d32f890ca1581",
"type" : "ACCESS_PROFILE"
} ]
}"@
# Submit Access Request
try {
$Result = ConvertFrom-JsonToAccessRequest -Json $AccessRequest
New-AccessRequest -AccessRequest $Result
# Below is a request that includes all optional parameters
# New-AccessRequest -AccessRequest $Result
} catch {
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling New-AccessRequest"
Write-Host $_.ErrorDetails
}
get-access-request-config
This endpoint returns the current access-request configuration.
Parameters
Param Type | Name | Data Type | Required | Description |
---|
Return type
Responses
Code | Description | Data Type |
---|---|---|
200 | Access Request Configuration Details. | AccessRequestConfig |
400 | Client Error - Returned if the request body is invalid. | ErrorResponseDto |
401 | Unauthorized - Returned if there is no authorization header, or if the JWT token is expired. | ListAccessProfiles401Response |
403 | Forbidden - Returned if the user you are running as, doesn't have access to this end-point. | ErrorResponseDto |
429 | 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. | ListAccessProfiles429Response |
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto |
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
Example
# Get Access Request Configuration
try {
Get-AccessRequestConfig
# Below is a request that includes all optional parameters
# Get-AccessRequestConfig
} catch {
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-AccessRequestConfig"
Write-Host $_.ErrorDetails
}
list-access-request-status
Use this API to return a list of access request statuses based on the specified query parameters. If an access request was made for access that an identity already has, the API ignores the access request. These ignored requests do not display in the list of access request statuses. Any user with any user level can get the status of their own access requests. A user with ORG_ADMIN is required to call this API to get a list of statuses for other users.
Parameters
Param Type | Name | Data Type | Required | Description |
---|---|---|---|---|
Query | RequestedFor | String | (optional) | Filter the results by the identity the requests were made for. me indicates the current user. Mutually exclusive with regarding-identity. |
Query | RequestedBy | String | (optional) | Filter the results by the identity who made the requests. me indicates the current user. Mutually exclusive with regarding-identity. |
Query | RegardingIdentity | String | (optional) | Filter the results by the specified identity who is either the requester or target of the requests. me indicates the current user. Mutually exclusive with requested-for and requested-by. |
Query | AssignedTo | String | (optional) | Filter the results by the specified identity who is the owner of the Identity Request Work Item. me indicates the current user. |
Query | Count | Boolean | (optional) (default to $false) | If this is true, the X-Total-Count response header populates with the number of results that would be returned if limit and offset were ignored. |
Query | Limit | Int32 | (optional) (default to 250) | Max number of results to return. |
Query | Offset | Int32 | (optional) | Offset into the full result set. Usually specified with limit to paginate through the results. Defaults to 0 if not specified. |
Query | Filters | String | (optional) | Filter results using the standard syntax described in V3 API Standard Collection Parameters Filtering is supported for the following fields and operators: accessRequestId: in accountActivityItemId: eq, in, ge, gt, le, lt, ne, isnull, sw created: eq, in, ge, gt, le, lt, ne, isnull, sw |
Query | Sorters | String | (optional) | Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: created, modified, accountActivityItemId, name |
Query | RequestState | String | (optional) | Filter the results by the state of the request. The only valid value is EXECUTING. |
Return type
Responses
Code | Description | Data Type |
---|---|---|
200 | List of requested item statuses. | RequestedItemStatus[] |
400 | Client Error - Returned if the request body is invalid. | ErrorResponseDto |
401 | Unauthorized - Returned if there is no authorization header, or if the JWT token is expired. | ListAccessProfiles401Response |
403 | Forbidden - Returned if the user you are running as, doesn't have access to this end-point. | ErrorResponseDto |
429 | 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. | ListAccessProfiles429Response |
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto |
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
Example
$RequestedFor = "2c9180877b2b6ea4017b2c545f971429" # String | Filter the results by the identity the requests were made for. *me* indicates the current user. Mutually exclusive with *regarding-identity*. (optional)
$RequestedBy = "2c9180877b2b6ea4017b2c545f971429" # String | Filter the results by the identity who made the requests. *me* indicates the current user. Mutually exclusive with *regarding-identity*. (optional)
$RegardingIdentity = "2c9180877b2b6ea4017b2c545f971429" # String | Filter the results by the specified identity who is either the requester or target of the requests. *me* indicates the current user. Mutually exclusive with *requested-for* and *requested-by*. (optional)
$AssignedTo = "2c9180877b2b6ea4017b2c545f971429" # String | Filter the results by the specified identity who is the owner of the Identity Request Work Item. *me* indicates the current user. (optional)
$Count = $false # Boolean | If this is true, the *X-Total-Count* response header populates with the number of results that would be returned if limit and offset were ignored. (optional) (default to $false)
$Limit = 100 # Int32 | Max number of results to return. (optional) (default to 250)
$Offset = 10 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. Defaults to 0 if not specified. (optional)
$Filters = 'accountActivityItemId eq "2c918086771c86df0177401efcdf54c0"' # String | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **accessRequestId**: *in* **accountActivityItemId**: *eq, in, ge, gt, le, lt, ne, isnull, sw* **created**: *eq, in, ge, gt, le, lt, ne, isnull, sw* (optional)
$Sorters = "created" # String | Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results) Sorting is supported for the following fields: **created, modified, accountActivityItemId, name** (optional)
$RequestState = "request-state=EXECUTING" # String | Filter the results by the state of the request. The only valid value is *EXECUTING*. (optional)
# Access Request Status
try {
Get-AccessRequestStatus
# Below is a request that includes all optional parameters
# Get-AccessRequestStatus -RequestedFor $RequestedFor -RequestedBy $RequestedBy -RegardingIdentity $RegardingIdentity -AssignedTo $AssignedTo -Count $Count -Limit $Limit -Offset $Offset -Filters $Filters -Sorters $Sorters -RequestState $RequestState
} catch {
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-AccessRequestStatus"
Write-Host $_.ErrorDetails
}
set-access-request-config
This endpoint replaces the current access-request configuration.
Parameters
Param Type | Name | Data Type | Required | Description |
---|---|---|---|---|
Body | AccessRequestConfig | AccessRequestConfig | True |
Return type
Responses
Code | Description | Data Type |
---|---|---|
200 | Access Request Configuration Details. | AccessRequestConfig |
400 | Client Error - Returned if the request body is invalid. | ErrorResponseDto |
401 | Unauthorized - Returned if there is no authorization header, or if the JWT token is expired. | ListAccessProfiles401Response |
403 | Forbidden - Returned if the user you are running as, doesn't have access to this end-point. | ErrorResponseDto |
429 | 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. | ListAccessProfiles429Response |
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto |
HTTP request headers
- Content-Type: application/json
- Accept: application/json
Example
$AccessRequestConfig = @"{
"requestOnBehalfOfConfig" : {
"allowRequestOnBehalfOfEmployeeByManager" : true,
"allowRequestOnBehalfOfAnyoneByAnyone" : true
},
"approvalReminderAndEscalationConfig" : {
"fallbackApproverRef" : {
"name" : "Alison Ferguso",
"id" : "5168015d32f890ca15812c9180835d2e",
"type" : "IDENTITY",
"email" : "alison.ferguso@identitysoon.com"
},
"maxReminders" : 1,
"daysUntilEscalation" : 0,
"daysBetweenReminders" : 0
},
"autoApprovalEnabled" : true,
"entitlementRequestConfig" : {
"requestCommentsRequired" : false,
"deniedCommentsRequired" : false,
"allowEntitlementRequest" : true,
"grantRequestApprovalSchemes" : "entitlementOwner, sourceOwner, manager, workgroup:2c918084660f45d6016617daa9210584"
},
"reauthorizationEnabled" : true,
"approvalsMustBeExternal" : true
}"@
# Update Access Request Configuration
try {
$Result = ConvertFrom-JsonToAccessRequestConfig -Json $AccessRequestConfig
Set-AccessRequestConfig -AccessRequestConfig $Result
# Below is a request that includes all optional parameters
# Set-AccessRequestConfig -AccessRequestConfig $Result
} catch {
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Set-AccessRequestConfig"
Write-Host $_.ErrorDetails
}