PersonalAccessTokens

Use this API to implement personal access token (PAT) functionality. With this functionality in place, users can use PATs as an alternative to passwords for authentication in Identity Security Cloud.

PATs embed user information into the client ID and secret. This replaces the API clients' need to store and provide a username and password to establish a connection, improving Identity Security Cloud organizations' integration security.

In Identity Security Cloud, users can do the following to create and manage their PATs: Select the dropdown menu under their names, select Preferences, and then select Personal Access Tokens. They must then provide a description about the token's purpose. They can then select 'Create Token' at the bottom of the page to generate and view the Secret and Client ID.

Refer to Managing Personal Access Tokens for more information about PATs.

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

Method	HTTP request	Description
New-PersonalAccessToken	POST /personal-access-tokens	Create Personal Access Token
Remove-PersonalAccessToken	DELETE /personal-access-tokens/{id}	Delete Personal Access Token
Get-PersonalAccessTokens	GET /personal-access-tokens	List Personal Access Tokens
Update-PersonalAccessToken	PATCH /personal-access-tokens/{id}	Patch Personal Access Token

create-personal-access-token

This creates a personal access token.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Body	CreatePersonalAccessTokenRequest	CreatePersonalAccessTokenRequest	True	Name and scope of personal access token.

Return type

CreatePersonalAccessTokenResponse

Responses

Code	Description	Data Type
200	Created. Note - this is the only time Personal Access Tokens' secret attribute will be displayed.	CreatePersonalAccessTokenResponse
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

$CreatePersonalAccessTokenRequest = @"{
  "scope" : [ "demo:personal-access-token-scope:first", "demo:personal-access-token-scope:second" ],
  "accessTokenValiditySeconds" : 36900,
  "name" : "NodeJS Integration"
}"@

# Create Personal Access Token

try {
    $Result = ConvertFrom-JsonToCreatePersonalAccessTokenRequest -Json $CreatePersonalAccessTokenRequest
    New-PersonalAccessToken -CreatePersonalAccessTokenRequest $Result 
    
    # Below is a request that includes all optional parameters
    # New-PersonalAccessToken -CreatePersonalAccessTokenRequest $Result  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling New-PersonalAccessToken"
    Write-Host $_.ErrorDetails
}

[Back to top]

delete-personal-access-token

This deletes a personal access token.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	Id	String	True	The personal access token id

Return type

(empty response body)

Responses

Code	Description	Data Type
204	No content.
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: Not defined
• Accept: application/json

Example

$Id = "ef38f94347e94562b5bb8424a56397d8" # String | The personal access token id

# Delete Personal Access Token

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

[Back to top]

list-personal-access-tokens

This gets a collection of personal access tokens associated with the optional owner-id. query parameter. If the owner-id query parameter is omitted, all personal access tokens for a tenant will be retrieved, but the caller must have the 'idn:all-personal-access-tokens:read' right.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Query	OwnerId	String	(optional)	The identity ID of the owner whose personal access tokens should be listed. If ""me"", the caller should have the following right: 'idn:my-personal-access-tokens:read' If an actual owner ID or if the owner-id parameter is omitted in the request, the caller should have the following right: 'idn:all-personal-access-tokens:read'. If the caller has the following right, then managed personal access tokens associated with owner-id will be retrieved: 'idn:managed-personal-access-tokens:read'
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: lastUsed: le, isnull

Return type

GetPersonalAccessTokenResponse[]

Responses

Code	Description	Data Type
200	List of personal access tokens.	GetPersonalAccessTokenResponse[]
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

$OwnerId = "2c9180867b50d088017b554662fb281e" # String | The identity ID of the owner whose personal access tokens should be listed.  If ""me"", the caller should have the following right: 'idn:my-personal-access-tokens:read' If an actual owner ID or if the `owner-id` parameter is omitted in the request,  the caller should have the following right: 'idn:all-personal-access-tokens:read'.  If the caller has the following right, then managed personal access tokens associated with `owner-id`  will be retrieved: 'idn:managed-personal-access-tokens:read' (optional)
$Filters = 'lastUsed le 2023-02-05T10:59:27.214Z' # 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:  **lastUsed**: *le, isnull* (optional)

# List Personal Access Tokens

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

[Back to top]

patch-personal-access-token

This performs a targeted update to the field(s) of a Personal Access Token. Changing scopes for a Personal Access Token does not impact existing bearer tokens. You will need to create a new bearer token to have the new scopes. Please note that it can take up to 20 minutes for scope changes to be seen on new bearer tokens.

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Path	Id	String	True	The Personal Access Token id
Body	JsonPatchOperation	[]JsonPatchOperation	True	A list of OAuth client update operations according to the JSON Patch standard. The following fields are patchable: * name * scope

Return type

GetPersonalAccessTokenResponse

Responses

Code	Description	Data Type
200	Indicates the PATCH operation succeeded, and returns the PAT's new representation.	GetPersonalAccessTokenResponse
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-patch+json
• Accept: application/json

Example

$Id = "ef38f94347e94562b5bb8424a56397d8" # String | The Personal Access Token id
 $JsonPatchOperation = @"{
  "op" : "replace",
  "path" : "/description",
  "value" : "New description"
}"@ # JsonPatchOperation[] | A list of OAuth client update operations according to the [JSON Patch](https://tools.ietf.org/html/rfc6902) standard.  The following fields are patchable: * name * scope 
 

# Patch Personal Access Token

try {
    $Result = ConvertFrom-JsonToJsonPatchOperation -Json $JsonPatchOperation
    Update-PersonalAccessToken -Id $Id -JsonPatchOperation $Result 
    
    # Below is a request that includes all optional parameters
    # Update-PersonalAccessToken -Id $Id -JsonPatchOperation $Result  
} catch {
    Write-Host $_.Exception.Response.StatusCode.value__ "Exception occurred when calling Update-PersonalAccessToken"
    Write-Host $_.ErrorDetails
}

[Back to top]