RoleInsights

All URIs are relative to https://sailpoint.api.identitynow.com/beta

Method	HTTP request	Description
New-BetaRoleInsightRequests	POST `/role-insights/requests`	Generate insights for roles
Invoke-BetaDownloadRoleInsightsEntitlementsChanges	GET `/role-insights/{insightId}/entitlement-changes/download`	Download entitlement insights for a role
Get-BetaEntitlementChangesIdentities	GET `/role-insights/{insightId}/entitlement-changes/{entitlementId}/identities`	Get identities for a suggested entitlement (for a role)
Get-BetaRoleInsight	GET `/role-insights/{insightId}`	Get a single role insight
Get-BetaRoleInsights	GET `/role-insights`	Get role insights
Get-BetaRoleInsightsCurrentEntitlements	GET `/role-insights/{insightId}/current-entitlements`	Get current entitlement for a role
Get-BetaRoleInsightsEntitlementsChanges	GET `/role-insights/{insightId}/entitlement-changes`	Get entitlement insights for a role
Get-BetaRoleInsightsRequests	GET `/role-insights/requests/{id}`	Returns metadata from prior request.
Get-BetaRoleInsightsSummary	GET `/role-insights/summary`	Get role insights summary information

create-role-insight-requests

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Submits a create role insights request to the role insights application. At this time there are no parameters. All business roles will be processed for the customer.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description

Return type

RoleInsightsResponse

Responses

Code	Description	Data Type
201	Submitted a role insights generation request	RoleInsightsResponse
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.	ListAccessModelMetadataAttribute401Response
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.	ListAccessModelMetadataAttribute429Response
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

# Generate insights for roles

try {
    New-BetaRoleInsightRequests 
    
    # Below is a request that includes all optional parameters
    # New-BetaRoleInsightRequests  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling New-BetaRoleInsightRequests"
    Write-Host $_.ErrorDetails
}

[Back to top]

download-role-insights-entitlements-changes

This endpoint returns the entitlement insights for a role.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	InsightId	String	True	The role insight id
Query	Sorters	String	(optional)	Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: identitiesWithAccess The default sort is identitiesWithAccess in descending order.
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: name: sw description: sw

Return type

String

Responses

Code	Description	Data Type
200	Succeeded. Returns a csv file containing a list of entitlements to be added for a role.	String
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: text/csv, application/json

Example

$InsightId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insight id
$Sorters = "identitiesWithAccess" # 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: **identitiesWithAccess**  The default sort is **identitiesWithAccess** in descending order. (optional)
$Filters = 'name sw "r"' # 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:  **name**: *sw*  **description**: *sw* (optional)

# Download entitlement insights for a role

try {
    Invoke-BetaDownloadRoleInsightsEntitlementsChanges -InsightId $InsightId 
    
    # Below is a request that includes all optional parameters
    # Invoke-BetaDownloadRoleInsightsEntitlementsChanges -InsightId $InsightId -Sorters $Sorters -Filters $Filters  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Invoke-BetaDownloadRoleInsightsEntitlementsChanges"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-entitlement-changes-identities

Role insights suggests entitlements to be added for a role. This endpoint returns a list of identities in the role, with or without the entitlements, for a suggested entitlement so that the user can see which identities would be affected if the suggested entitlement were to be added to the role.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	InsightId	String	True	The role insight id
Path	EntitlementId	String	True	The entitlement id
Query	HasEntitlement	Boolean	(optional) (default to $false)	Identity has this entitlement or not
Query	Offset	Int32	(optional) (default to 0)	Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.
Query	Limit	Int32	(optional) (default to 250)	Max number of results to return. See V3 API Standard Collection Parameters for more information.
Query	Count	Boolean	(optional) (default to $false)	If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored. Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used. See V3 API Standard Collection Parameters for more information.
Query	Sorters	String	(optional)	Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: name
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: name: sw

Return type

RoleInsightsIdentities[]

Responses

Code	Description	Data Type
200	Succeeded. Returns a list of identities with or without the entitlement.	RoleInsightsIdentities[]
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$InsightId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insight id
$EntitlementId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The entitlement id
$HasEntitlement = $true # Boolean | Identity has this entitlement or not (optional) (default to $false)
$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
$Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 250)
$Count = $true # Boolean | If *true* it will populate the *X-Total-Count* response header with the number of results that would be returned if *limit* and *offset* were ignored.  Since requesting a total count can have a performance impact, it is recommended not to send **count=true** if that value will not be used.  See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to $false)
$Sorters = "name" # 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: **name** (optional)
$Filters = 'name sw "Jan"' # 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:  **name**: *sw* (optional)

# Get identities for a suggested entitlement (for a role)

try {
    Get-BetaEntitlementChangesIdentities -InsightId $InsightId -EntitlementId $EntitlementId 
    
    # Below is a request that includes all optional parameters
    # Get-BetaEntitlementChangesIdentities -InsightId $InsightId -EntitlementId $EntitlementId -HasEntitlement $HasEntitlement -Offset $Offset -Limit $Limit -Count $Count -Sorters $Sorters -Filters $Filters  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaEntitlementChangesIdentities"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insight

This endpoint gets role insights information for a role.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	InsightId	String	True	The role insight id

Return type

RoleInsight

Responses

Code	Description	Data Type
200	Succeeded. Returns information about insights for a single role.	RoleInsight
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$InsightId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insight id

# Get a single role insight

try {
    Get-BetaRoleInsight -InsightId $InsightId 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsight -InsightId $InsightId  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsight"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insights

This method returns detailed role insights for each role.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Query	Offset	Int32	(optional) (default to 0)	Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.
Query	Limit	Int32	(optional) (default to 250)	Max number of results to return. See V3 API Standard Collection Parameters for more information.
Query	Count	Boolean	(optional) (default to $false)	If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored. Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used. See V3 API Standard Collection Parameters for more information.
Query	Sorters	String	(optional)	Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: numberOfUpdates, identitiesWithAccess, totalNumberOfIdentities
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: name: sw ownerName: sw description: sw

Return type

RoleInsight[]

Responses

Code	Description	Data Type
200	Succeeded. Returns a list of roles with information about insights for each role.	RoleInsight[]
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
$Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 250)
$Count = $true # Boolean | If *true* it will populate the *X-Total-Count* response header with the number of results that would be returned if *limit* and *offset* were ignored.  Since requesting a total count can have a performance impact, it is recommended not to send **count=true** if that value will not be used.  See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to $false)
$Sorters = "numberOfUpdates" # 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: **numberOfUpdates, identitiesWithAccess, totalNumberOfIdentities** (optional)
$Filters = 'name sw "John"' # 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:  **name**: *sw*  **ownerName**: *sw*  **description**: *sw* (optional)

# Get role insights

try {
    Get-BetaRoleInsights 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsights -Offset $Offset -Limit $Limit -Count $Count -Sorters $Sorters -Filters $Filters  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsights"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insights-current-entitlements

This endpoint gets the entitlements for a role. The term "current" is to distinguish from the entitlement(s) an insight might recommend adding.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	InsightId	String	True	The role insight id
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: name: sw description: sw

Return type

RoleInsightsEntitlement[]

Responses

Code	Description	Data Type
200	Succeeded. Returns a list of current or pre-existing entitlements for a role.	RoleInsightsEntitlement[]
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$InsightId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insight id
$Filters = 'name sw "r"' # 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:  **name**: *sw*  **description**: *sw* (optional)

# Get current entitlement for a role

try {
    Get-BetaRoleInsightsCurrentEntitlements -InsightId $InsightId 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsightsCurrentEntitlements -InsightId $InsightId -Filters $Filters  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsightsCurrentEntitlements"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insights-entitlements-changes

This endpoint returns entitlement insights for a role.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	InsightId	String	True	The role insight id
Query	Sorters	String	(optional)	Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: identitiesWithAccess, name
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: name: sw description: sw

Return type

RoleInsightsEntitlementChanges[]

Responses

Code	Description	Data Type
200	Succeeded. Returns a list of entitlements to be added for a role.	RoleInsightsEntitlementChanges[]
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$InsightId = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insight id
$Sorters = "MySorters" # 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: **identitiesWithAccess, name** (optional)
$Filters = 'name sw "Admin"' # 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:  **name**: *sw*  **description**: *sw* (optional)

# Get entitlement insights for a role

try {
    Get-BetaRoleInsightsEntitlementsChanges -InsightId $InsightId 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsightsEntitlementsChanges -InsightId $InsightId -Sorters $Sorters -Filters $Filters  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsightsEntitlementsChanges"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insights-requests

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

This endpoint returns details of a prior role insights request.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	Id	String	True	The role insights request id

Return type

RoleInsightsResponse

Responses

Code	Description	Data Type
200	Succeeded. Returns details of an earlier role insights request.	RoleInsightsResponse
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.	ListAccessModelMetadataAttribute401Response
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.	ListAccessModelMetadataAttribute429Response
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

$Id = "8c190e67-87aa-4ed9-a90b-d9d5344523fb" # String | The role insights request id

# Returns metadata from prior request.

try {
    Get-BetaRoleInsightsRequests -Id $Id 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsightsRequests -Id $Id  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsightsRequests"
    Write-Host $_.ErrorDetails
}

[Back to top]

get-role-insights-summary

This method returns high level summary information for role insights for a customer.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description

Return type

RoleInsightsSummary

Responses

Code	Description	Data Type
200	Succeeded. Returns high level counts.	RoleInsightsSummary
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.	ListAccessModelMetadataAttribute401Response
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto

HTTP request headers

Content-Type: Not defined
Accept: application/json

Example

# Get role insights summary information

try {
    Get-BetaRoleInsightsSummary 
    
    # Below is a request that includes all optional parameters
    # Get-BetaRoleInsightsSummary  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Get-BetaRoleInsightsSummary"
    Write-Host $_.ErrorDetails
}

[Back to top]

create-role-insight-requests​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

download-role-insights-entitlements-changes​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-entitlement-changes-identities​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insight​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insights​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insights-current-entitlements​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insights-entitlements-changes​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insights-requests​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-insights-summary​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

create-role-insight-requests

Parameters

Return type

Responses

HTTP request headers

Example

download-role-insights-entitlements-changes

Parameters

Return type

Responses

HTTP request headers

Example

get-entitlement-changes-identities

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insight

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insights

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insights-current-entitlements

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insights-entitlements-changes

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insights-requests

Parameters

Return type

Responses

HTTP request headers

Example

get-role-insights-summary

Parameters

Return type

Responses

HTTP request headers

Example