mirror of
https://github.com/LukeHagar/developer.sailpoint.com.git
synced 2025-12-09 12:27:47 +00:00
adding powershell sdk docs back
This commit is contained in:
darrell-thobe-sp
@@ -0,0 +1,385 @@
|
||||
---
|
||||
id: access-requests
|
||||
title: AccessRequests
|
||||
pagination_label: AccessRequests
|
||||
sidebar_label: AccessRequests
|
||||
sidebar_class_name: powershellsdk
|
||||
keywords: ['powershell', 'PowerShell', 'sdk', 'AccessRequests', 'AccessRequests']
|
||||
slug: /tools/sdk/powershell/v3/methods/access-requests
|
||||
tags: ['SDK', 'Software Development Kit', 'AccessRequests', 'AccessRequests']
|
||||
---
|
||||
|
||||
|
||||
# AccessRequests
|
||||
|
||||
All URIs are relative to *https://sailpoint.api.identitynow.com/v3*
|
||||
|
||||
Method | HTTP request | Description
|
||||
------------- | ------------- | -------------
|
||||
[**Suspend-AccessRequest**](#cancel-access-request) | **POST** `/access-requests/cancel` | Cancel Access Request
|
||||
[**New-AccessRequest**](#create-access-request) | **POST** `/access-requests` | Submit Access Request
|
||||
[**Get-AccessRequestConfig**](#get-access-request-config) | **GET** `/access-request-config` | Get Access Request Configuration
|
||||
[**Get-AccessRequestStatus**](#list-access-request-status) | **GET** `/access-request-status` | Access Request Status
|
||||
[**Set-AccessRequestConfig**](#set-access-request-config) | **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**](../models/cancel-access-request) | True |
|
||||
|
||||
### Return type
|
||||
|
||||
[**SystemCollectionsHashtable**](https://learn.microsoft.com/en-us/dotnet/api/system.collections.hashtable?view=net-9.0)
|
||||
|
||||
### 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
|
||||
```powershell
|
||||
$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 $CancelAccessRequest
|
||||
} catch {
|
||||
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Suspend-AccessRequest"
|
||||
Write-Host $_.ErrorDetails
|
||||
}
|
||||
```
|
||||
|
||||
[[Back to top]](#)
|
||||
|
||||
## 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](https://developer.sailpoint.com/idn/api/v3/list-access-request-status) or the [Pending Access Request Approvals](https://developer.sailpoint.com/idn/api/v3/list-pending-approvals) APIs. You can also
|
||||
use the [Search API](https://developer.sailpoint.com/idn/api/v3/search) 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](https://developer.sailpoint.com/idn/api/v3/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](https://developer.sailpoint.com/idn/api/v3/get-access-request-config) 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. The `removeDate` 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**](../models/access-request) | True |
|
||||
|
||||
### Return type
|
||||
|
||||
[**AccessRequestResponse**](../models/access-request-response)
|
||||
|
||||
### 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
|
||||
```powershell
|
||||
$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 $AccessRequest
|
||||
} catch {
|
||||
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling New-AccessRequest"
|
||||
Write-Host $_.ErrorDetails
|
||||
}
|
||||
```
|
||||
|
||||
[[Back to top]](#)
|
||||
|
||||
## get-access-request-config
|
||||
|
||||
This endpoint returns the current access-request configuration.
|
||||
|
||||
### Parameters
|
||||
Param Type | Name | Data Type | Required | Description
|
||||
------------- | ------------- | ------------- | ------------- | -------------
|
||||
|
||||
### Return type
|
||||
|
||||
[**AccessRequestConfig**](../models/access-request-config)
|
||||
|
||||
### 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
|
||||
```powershell
|
||||
# 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
|
||||
}
|
||||
```
|
||||
|
||||
[[Back to top]](#)
|
||||
|
||||
## 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](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*
|
||||
Query | Sorters | **String** | (optional) | 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**
|
||||
Query | RequestState | **String** | (optional) | Filter the results by the state of the request. The only valid value is *EXECUTING*.
|
||||
|
||||
### Return type
|
||||
|
||||
[**RequestedItemStatus[]**](../models/requested-item-status)
|
||||
|
||||
### 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
|
||||
```powershell
|
||||
$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
|
||||
}
|
||||
```
|
||||
|
||||
[[Back to top]](#)
|
||||
|
||||
## set-access-request-config
|
||||
|
||||
This endpoint replaces the current access-request configuration.
|
||||
|
||||
### Parameters
|
||||
Param Type | Name | Data Type | Required | Description
|
||||
------------- | ------------- | ------------- | ------------- | -------------
|
||||
Body | AccessRequestConfig | [**AccessRequestConfig**](../models/access-request-config) | True |
|
||||
|
||||
### Return type
|
||||
|
||||
[**AccessRequestConfig**](../models/access-request-config)
|
||||
|
||||
### 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
|
||||
```powershell
|
||||
$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 $AccessRequestConfig
|
||||
} catch {
|
||||
Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Set-AccessRequestConfig"
|
||||
Write-Host $_.ErrorDetails
|
||||
}
|
||||
```
|
||||
|
||||
[[Back to top]](#)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user