LukeParke/developer.sailpoint.com
1
0
Fork 0
mirror of https://github.com/LukeHagar/developer.sailpoint.com.git synced 2025-12-09 20:37:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Prettified Code!

Browse Source
This commit is contained in:
darrell-thobe-sp
2024-04-18 10:31:05 +00:00
committed by GitHub Action
parent f5b6aaf14f
commit 2cd5ccfc81
223 changed files with 40526 additions and 28073 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/api/api-specifications.md
View File

@@ -11,11 +11,11 @@ slug: /api/api-specifications
tags: ['API Specifications']
---
## Overview
## Overview
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
The API specifications contain detailed information of how to send requests to each API endpoint, as well as example requests and responses. They also include essential information about how to use the APIs and guides you can follow to get started.
The API specifications contain detailed information of how to send requests to each API endpoint, as well as example requests and responses. They also include essential information about how to use the APIs and guides you can follow to get started.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
@@ -24,8 +24,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).

218
docs/api/authentication.md
View File

@@ -15,20 +15,13 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
## Overview
With SailPoint's Identity Security Cloud (ISC) APIs, you can extend your ISC platform far beyond its current capabilities.
To be able to do so, you must first authenticate to the ISC APIs.
Authentication is the act of validating a user's identity, generally by passing some kind of credentials.
A fast, simple way to authenticate to the APIs is to generate a [personal access token](#generate-a-personal-access-token) and pass that token.
With SailPoint's Identity Security Cloud (ISC) APIs, you can extend your ISC platform far beyond its current capabilities. To be able to do so, you must first authenticate to the ISC APIs. Authentication is the act of validating a user's identity, generally by passing some kind of credentials. A fast, simple way to authenticate to the APIs is to generate a [personal access token](#generate-a-personal-access-token) and pass that token.
If the PAT is valid, the API responds with a JSON Web Token (JWT) `access_token` that you can provide to authorize your API requests.
Authorization is the act of validating the user's permission to access a given resource.
A successful API request must include the `access_token` in the `Authorization` request header.
If the PAT is valid, the API responds with a JSON Web Token (JWT) `access_token` that you can provide to authorize your API requests. Authorization is the act of validating the user's permission to access a given resource. A successful API request must include the `access_token` in the `Authorization` request header.
This JWT `access_token` grants access matching that of the user who generated the PAT.
For example, if the user who generated the PAT is an admin, the returned JWT `access_token` would grant admin access to the APIs.
This JWT `access_token` grants access matching that of the user who generated the PAT. For example, if the user who generated the PAT is an admin, the returned JWT `access_token` would grant admin access to the APIs.
This diagram shows the flow of this authentication/authorization process:
This diagram shows the flow of this authentication/authorization process:
<div align="center">
@@ -49,23 +42,23 @@ sequenceDiagram
</div>
The flow involves these four key steps:
1. **Access Token Request**: The HTTP client (a script, application, Postman, cURL, etc.) makes a request to ISC to get a JWT `access_token`.
2. **Access Token Response**: If the request is valid, ISC responds to the HTTP client with a JWT `access_token`.
3. **API Request**: The HTTP client makes a request to an ISC endpoint with the header, `Authorization: Bearer {access_token}`.
4. **API Response**: If both the request itself and the JWT `access_token` in its header are valid, ISC responds to the client.
If you encounter unexpected errors, refer to the [Troubleshooting](#troubleshooting) section of this document.
The flow involves these four key steps:
The idea is that once you have authenticated to the ISC APIs and you have received an `access_token`, you can use that `access_token` to provide authorization for your API requests.
1. **Access Token Request**: The HTTP client (a script, application, Postman, cURL, etc.) makes a request to ISC to get a JWT `access_token`.
2. **Access Token Response**: If the request is valid, ISC responds to the HTTP client with a JWT `access_token`.
3. **API Request**: The HTTP client makes a request to an ISC endpoint with the header, `Authorization: Bearer {access_token}`.
4. **API Response**: If both the request itself and the JWT `access_token` in its header are valid, ISC responds to the client. If you encounter unexpected errors, refer to the [Troubleshooting](#troubleshooting) section of this document.
This document includes all the information you need to know to engage in this authentication/authorization process, as well as a guide on how to get started.
The idea is that once you have authenticated to the ISC APIs and you have received an `access_token`, you can use that `access_token` to provide authorization for your API requests.
This document includes all the information you need to know to engage in this authentication/authorization process, as well as a guide on how to get started.
## Get started
Read this guide to learn how to authenticate to SailPoint's ISC APIs.
Read this guide to learn how to authenticate to SailPoint's ISC APIs.
To authenticate to the ISC APIs, you must be able to connect to your tenant to send the access token request. To do so, you need to do the following:
To authenticate to the ISC APIs, you must be able to connect to your tenant to send the access token request.
To do so, you need to do the following:
1. [Find your tenant's OAuth details](#find-your-tenant's-oauth-details)
2. [Generate personal access token](#generate-personal-access-token)
3. [Choose authorization grant flow](#choose-authorization-grant-flow)
@@ -73,21 +66,19 @@ To do so, you need to do the following:
### Find your tenant's OAuth details
Your tenant's OAuth details refer to the details you need to know to connect it to the APIs.
You need to know your tenant's name, its `authorizeEndpoint` URL, and its `tokenEndpoint` URL.
Your tenant's OAuth details refer to the details you need to know to connect it to the APIs. You need to know your tenant's name, its `authorizeEndpoint` URL, and its `tokenEndpoint` URL.
Your ISC instance is likely using the domain name supplied by SailPoint (`{tenant}.api.identitynow.com`), in which case, the tenant name is in the URL.
This is assumed to be the case in this guide.
However, if your ISC instance is using a vanity URL, you must enter this URL into your browser to get your OAuth info:
`https://{tenant}.api.identitynow.com/oauth/info`
Your ISC instance is likely using the domain name supplied by SailPoint (`{tenant}.api.identitynow.com`), in which case, the tenant name is in the URL. This is assumed to be the case in this guide.
However, if your ISC instance is using a vanity URL, you must enter this URL into your browser to get your OAuth info: `https://{tenant}.api.identitynow.com/oauth/info`
If you have admin access but don't know your tenant name, you can learn it by following these steps:
If you have admin access but don't know your tenant name, you can learn it by following these steps:
1. Log into your ISC instance.
2. Select the 'Dashboard' dropdown.
3. Select 'Overview'.
4. Find the tenant name ('Org Name') in the dashboard's `Org Details` section.
2. Select the 'Dashboard' dropdown.
3. Select 'Overview'.
4. Find the tenant name ('Org Name') in the dashboard's `Org Details` section.
This is an example of the OAuth details of the tenant, "iga-acme-sb":
This is an example of the OAuth details of the tenant, "iga-acme-sb":
```json
{
@@ -101,25 +92,21 @@ This is an example of the OAuth details of the tenant, "iga-acme-sb":
}
```
You can use the `authorizeEndpoint` and `tokenEndpoint` URLs from this example to test out the different authentication methods listed in this guide.
You can use the `authorizeEndpoint` and `tokenEndpoint` URLs from this example to test out the different authentication methods listed in this guide.
### Generate a personal access token
### Generate a personal access token
A personal access token (PAT) is a method of authenticating to an API as a user without providing a username and password.
PATs are primarily used in scripts or programs that lack an easy way to implement an OAuth2 flow but need to call API endpoints that require user context.
PATs are also convenient for use in tools like [Postman](https://www.postman.com/) when you are exploring and testing the APIs.
A personal access token (PAT) is a method of authenticating to an API as a user without providing a username and password. PATs are primarily used in scripts or programs that lack an easy way to implement an OAuth2 flow but need to call API endpoints that require user context. PATs are also convenient for use in tools like [Postman](https://www.postman.com/) when you are exploring and testing the APIs.
Any ISC user can generate a PAT.
To do so, follow these steps:
1. Select **Preferences** from the drop-down menu under your username, then **Personal Access Tokens** on the left.
You can also go directly to the page by using this URL (replace `{tenant}` with your Identity Security Cloud tenant): `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`
Any ISC user can generate a PAT. To do so, follow these steps:
1. Select **Preferences** from the drop-down menu under your username, then **Personal Access Tokens** on the left. You can also go directly to the page by using this URL (replace `{tenant}` with your Identity Security Cloud tenant): `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`
2. Click **New Token** and enter a meaningful description to help differentiate the token from others.
:::caution
The **New Token** button will be disabled when you reach the limit of 10 personal access tokens per user.
To avoid reaching this limit, it is recommended that you delete any tokens that are no longer necessary.
The **New Token** button will be disabled when you reach the limit of 10 personal access tokens per user. To avoid reaching this limit, it is recommended that you delete any tokens that are no longer necessary.
:::
@@ -135,29 +122,25 @@ After you create the token, the value of the `Client ID` will be visible in the
To generate a personal access token from the API, use the [create personal access token endpoint](/docs/api/beta/create-personal-access-token).
Once you have created the PAT and you know its `Client ID` and `Client Secret`, you have everything you need to follow the [Client Credentials Grant Flow](#request-access-token-with-client-credentials-grant-flow) and use the PAT to generate an `access_token`.
You will need this `access_token` to authenticate your requests to the APIs.
Once you have created the PAT and you know its `Client ID` and `Client Secret`, you have everything you need to follow the [Client Credentials Grant Flow](#request-access-token-with-client-credentials-grant-flow) and use the PAT to generate an `access_token`. You will need this `access_token` to authenticate your requests to the APIs.
### Choose authorization grant flow
There are several different authorization flows that OAuth 2.0 supports, and each has a grant-type defining its different use cases.
You must choose the one that best serves your purposes.
This document covers these three common flows:
There are several different authorization flows that OAuth 2.0 supports, and each has a grant-type defining its different use cases. You must choose the one that best serves your purposes. This document covers these three common flows:
1. [**Client Credentials**](https://oauth.net/2/grant-types/client-credentials/) - Clients use this grant type to obtain a JWT `access_token` without user involvement such as scripts, programs or system to system integration.
2. [**Authorization Code**](https://oauth.net/2/grant-types/authorization-code/) - Clients use this grant type to exchange an authorization code for an `access_token`. Authorization codes are mainly used by web applications because there is a login into ISC with a subsequent redirect back to the web application/client.
3. [**Refresh Token**](https://oauth.net/2/grant-types/refresh-token/) - Clients use this grant type to exchange a refresh token for a new `access_token` when the existing `access_token` has expired. This allows clients to continue using the APIs without having to re-authenticate as frequently. This grant type is commonly used together with `Authorization Code` to prevent a user from having to log in several times per day.
One way to determine which authorization flow you need to use is to look at the specification for the endpoint you want to use.
The endpoint will have the supported OAuth flows listed under the 'Authorization' dropdown, like the [List Access Profiles endpoint](https://developer.sailpoint.com/docs/api/beta/list-access-profiles):
One way to determine which authorization flow you need to use is to look at the specification for the endpoint you want to use. The endpoint will have the supported OAuth flows listed under the 'Authorization' dropdown, like the [List Access Profiles endpoint](https://developer.sailpoint.com/docs/api/beta/list-access-profiles):
![Authorization Dropdown](./img/authorization/authorization-dropdown.png)
For more information about how to choose the best grant flow for your use case, refer to [Grant Flow Use Cases](#grant-flow-use-cases)
The guide will detail the three different authorization grant flows you can use to request the access token you need to authenticate your requests.
The guide will detail the three different authorization grant flows you can use to request the access token you need to authenticate your requests.
### Request access token with client credentials grant flow
### Request access token with client credentials grant flow
Clients use the 'Client Credentials' grant type to obtain access tokens without user involvement. This is the simplest authentication flow.
@@ -185,25 +168,25 @@ An OAuth 2.0 client using the client credentials grant flow must have `CLIENT_CR
This is the overall authorization flow:
1. The client first submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token
```
The request includes the client credential information passed in the request body, as shown in this example using [Postman](https://www.getpostman.com):
The request includes the client credential information passed in the request body, as shown in this example using [Postman](https://www.getpostman.com):
![OAuth Client Credentials Form Data](./img/authentication/oauth-client-credentials-form-data.png)
This example shows how to pass the information with form-data in the request body. You can also use these options to pass in the information:
This example shows how to pass the information with form-data in the request body. You can also use these options to pass in the information:
- Use x-www-form-urlencoded data to pass in the client credential information in the request body.
- Use query parameters to pass the information in the request URL. The request URL will look like this:
- Use x-www-form-urlencoded data to pass in the client credential information in the request body.
- Use query parameters to pass the information in the request URL. The request URL will look like this:
```text
https://{tenant}.api.identitynow.com/oauth/token?grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}
```
- If you are using Postman, you can use the 'Authorization' tab to pass in the client credentials. If you use this option, you must also specify the access token URL: https://{tenant}.api.identitynow.com/oauth/token
The OAuth 2.0 token request must include this information:
The OAuth 2.0 token request must include this information:
| Key | Description |
| --- | --- |
@@ -221,23 +204,19 @@ curl --location 'https://{tenant}.api.identitynow.com/oauth/token' \
--form 'client_secret="{clientSecret}"'
```
2. ISC validates the token request and responds.
If the request is successful, the response contains a JWT access token.
For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
2. ISC validates the token request and responds. If the request is successful, the response contains a JWT access token. For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
Once you have the JWT access token, you can pass the token as a basic "Authorization" header in your requests using the OAuth endpoints.
Once you have the JWT access token, you can pass the token as a basic "Authorization" header in your requests using the OAuth endpoints.
To learn more about the OAuth client credentials grant flow, refer [here](https://oauth.net/2/grant-types/client-credentials/).
To learn more about the OAuth client credentials grant flow, refer [here](https://oauth.net/2/grant-types/client-credentials/).
### Request access token with authorization code grant flow
### Request access token with authorization code grant flow
Further Reading: [https://oauth.net/2/grant-types/authorization-code/](https://oauth.net/2/grant-types/authorization-code/)
Clients use this grant type to exchange an authorization code for an `access_token`.
This is mainly used for web apps because there is a login into ISC with a subsequent redirect back to the web app/client.
Clients use this grant type to exchange an authorization code for an `access_token`. This is mainly used for web apps because there is a login into ISC with a subsequent redirect back to the web app/client.
The OAuth 2.0 client you are using must have `AUTHORIZATION_CODE` as one of its grant types.
The redirect URLs must also match the list in the client as well:
The OAuth 2.0 client you are using must have `AUTHORIZATION_CODE` as one of its grant types. The redirect URLs must also match the list in the client as well:
```json
{
@@ -258,9 +237,9 @@ The redirect URLs must also match the list in the client as well:
<br></br>
The authorization code grant flow looks a little different because it involves the exchange of the access token and authorization code.
The authorization code grant flow looks a little different because it involves the exchange of the access token and authorization code.
This diagram shows the authorization code grant flow:
This diagram shows the authorization code grant flow:
<div align="center">
@@ -310,8 +289,7 @@ The token endpoint URL is `{tenant}.api.identitynow.com`, and the authorize URL
:::
7. ISC validates the token request and submits a response. If the request is successful, the response contains a JWT `access_token`.
For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
7. ISC validates the token request and submits a response. If the request is successful, the response contains a JWT `access_token`. For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
These are the query parameters in the OAuth 2.0 token request for the authorization code grant:
@@ -328,14 +306,14 @@ Here is an example OAuth 2.0 token request for the authorization code grant type
curl -X POST \
'https://example.api.identitynow.com/oauth/token?grant_type=authorization_code&client_id=b61429f5-203d-494c-94c3-04f54e17bc5c&code=6688LQJB0y652z6ZjFmkCKuBUjv2sTIqKS2JthWrZ7qlPgI9TClJ6FnpweEhO6w7&redirect_uri=https://myappdomain.com/oauth/redirect' \
-H 'cache-control: no-cache'
```
Once you have the JWT access token, you can pass the token as a basic "Authorization" header in your requests using the OAuth endpoints.
Once you have the JWT access token, you can pass the token as a basic "Authorization" header in your requests using the OAuth endpoints.
For more information about the OAuth authorization code grant flow, refer [here](https://oauth.net/2/grant-types/authorization-code/).
### Request access token with refresh token grant flow
### Request access token with refresh token grant flow
Clients use this grant type in order to exchange a refresh token for a new `access_token` once the existing `access_token` has expired. This allows clients to continue to have a valid `access_token` without the need for the user to login as frequently.
@@ -386,9 +364,9 @@ curl -X POST \
-H 'cache-control: no-cache'
```
Once you have the `refresh_token`, you can pass the `refresh_token` as a basic "Authorization" header in your requests using the OAuth endpoints, allowing your requests to continue to succeed without being affected by the expired `access_token`.
Once you have the `refresh_token`, you can pass the `refresh_token` as a basic "Authorization" header in your requests using the OAuth endpoints, allowing your requests to continue to succeed without being affected by the expired `access_token`.
For more information about the OAuth refresh token grant flow, refer [here](https://oauth.net/2/grant-types/refresh-token/).
For more information about the OAuth refresh token grant flow, refer [here](https://oauth.net/2/grant-types/refresh-token/).
### OAuth token response
@@ -415,9 +393,7 @@ A successful request using any of the grant flows to `https://{tenant}.api.ident
}
```
You can use the JWT `access_token` to authorize REST API calls through the ISC API gateway.
To use the `access_token`, simply include it in the `Authorization` header as a `Bearer` token.
This is an example V3 API request that has the access token in the header:
You can use the JWT `access_token` to authorize REST API calls through the ISC API gateway. To use the `access_token`, simply include it in the `Authorization` header as a `Bearer` token. This is an example V3 API request that has the access token in the header:
```bash
curl -X GET \
@@ -426,34 +402,27 @@ curl -X GET \
-H 'cache-control: no-cache'
```
Some of the other values can also be useful to know:
- The `expires_in` value describes the lifetime, in seconds, of the `access_token`.
For example, the value 749 means that the `access_token` will expire 12.5 minutes from the time the response was generated.
The exact expiration date is also contained within the `access_token`.
You can view this expiration time by decoding the JWT `access_token` using a tool like [jwt.io](https://jwt.io/).
Some of the other values can also be useful to know:
- The `refresh token` exists for use in the refresh token grant flow to replace the `access_token` when it expires.
However, the `refresh_token` will only be present if the API client has the `REFRESH_TOKEN` grant flow.
- The `expires_in` value describes the lifetime, in seconds, of the `access_token`. For example, the value 749 means that the `access_token` will expire 12.5 minutes from the time the response was generated. The exact expiration date is also contained within the `access_token`. You can view this expiration time by decoding the JWT `access_token` using a tool like [jwt.io](https://jwt.io/).
- The `user_id` and `identity_id` define the identity context of the person who authenticated.
However, these values aren't set for the client credentials grant type because it doesn't have a user context.
- The `refresh token` exists for use in the refresh token grant flow to replace the `access_token` when it expires. However, the `refresh_token` will only be present if the API client has the `REFRESH_TOKEN` grant flow.
With the JWT `access_token`, you can now successfully send authenticated ISC API requests. To learn more about authorization and the scopes you can apply to further control access to the APIs, refer to [Authorization](/docs/api/authorization).
- The `user_id` and `identity_id` define the identity context of the person who authenticated. However, these values aren't set for the client credentials grant type because it doesn't have a user context.
With the JWT `access_token`, you can now successfully send authenticated ISC API requests. To learn more about authorization and the scopes you can apply to further control access to the APIs, refer to [Authorization](/docs/api/authorization).
## More Information
This section of the document includes additional information about the authentication/authorization process, including some different use cases for the different authorization grant flows.
This section of the document includes additional information about the authentication/authorization process, including some different use cases for the different authorization grant flows.
### OAuth 2.0
The SailPoint authentication/authorization model is fully [OAuth 2.0](https://oauth.net/2/) compliant.
[OAuth 2.0](https://oauth.net/2/) is an industry-standard protocol for authorization.
It provides a variety of authorization flows for web applications, desktop applications, mobile phones, and devices.
This specification and its extensions are developed within the [IETF OAuth Working Group](https://www.ietf.org/mailman/listinfo/oauth).
### OAuth 2.0
The SailPoint authentication/authorization model is fully [OAuth 2.0](https://oauth.net/2/) compliant. [OAuth 2.0](https://oauth.net/2/) is an industry-standard protocol for authorization. It provides a variety of authorization flows for web applications, desktop applications, mobile phones, and devices. This specification and its extensions are developed within the [IETF OAuth Working Group](https://www.ietf.org/mailman/listinfo/oauth).
### JSON Web Token
The issued JWT `access_token` leverages the [JSON Web Token (JWT)](https://jwt.io/) standard.
JWT is an industry-standard protocol for creating access tokens which assert various claims about the resource who has authenticated.
The tokens have a specific structure consisting of a header, payload, and signature.
The issued JWT `access_token` leverages the [JSON Web Token (JWT)](https://jwt.io/) standard. JWT is an industry-standard protocol for creating access tokens which assert various claims about the resource who has authenticated. The tokens have a specific structure consisting of a header, payload, and signature.
A raw JWT might look like this:
@@ -513,43 +482,43 @@ You can check the JWT access token data online at [jwt.io](https://jwt.io).
### Grant flow use cases
This section describes some different use cases and which grant flow you would want to use for the different cases.
This section describes some different use cases and which grant flow you would want to use for the different cases.
#### Daily work or quick actions
For daily work or short, quick administrative actions, you can just use a PAT. This makes the process easier because you don't really need to worry about grant types - you can easily generate a PAT in the user interface (UI).
Follow these steps to do so:
Follow these steps to do so:
1. Log in to ISC.
2. Go to 'Preferences', then 'Personal Access Tokens', and [generate a PAT](#generate-a-personal-access-token).
3. The PAT's `client_id` and `client_secret` provide the necessary authentication to send API requests, without any grant flow.
2. Go to 'Preferences', then 'Personal Access Tokens', and [generate a PAT](#generate-a-personal-access-token).
3. The PAT's `client_id` and `client_secret` provide the necessary authentication to send API requests, without any grant flow.
#### Postman
[Postman](https://www.postman.com/) is a popular HTTP client you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the Identity Security Cloud API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the ISC API collections and stay up to date.
If you're using Postman, you have some different ways to set up your authorization.
You can just leverage the accessToken as mentioned above, or you can configure Postman to use OAuth 2.0 directly.
For more information about how to do so, refer [here](https://learning.postman.com/docs/sending-requests/authorization/).
If you're using Postman, you have some different ways to set up your authorization. You can just leverage the accessToken as mentioned above, or you can configure Postman to use OAuth 2.0 directly. For more information about how to do so, refer [here](https://learning.postman.com/docs/sending-requests/authorization/).
#### Web applications
#### Web applications
If you are making a web application, the best grant flow to use is the [Authorization Code grant flow](#request-access-token-with-authorization-grant-flow). This will allow users to be directed to ISC to login and then redirected back to the web application through a URL redirect. This also works well with Single Sign-on (SSO), strong authentication, and pass-through authentication mechanisms.
SailPoint doesn't recommend using a password grant flow for web applications because doing so would involve entering ISC credentials in the web application.
This flow also doesn't allow you to work with SSO, strong authentication, or pass-through authentication.
SailPoint doesn't recommend using a password grant flow for web applications because doing so would involve entering ISC credentials in the web application. This flow also doesn't allow you to work with SSO, strong authentication, or pass-through authentication.
#### Scripts, programs or system to system integration
If you are writing scripts, programs or system integrations that leverage the ISC APIs, the OAuth 2.0 grant you should use typically depends on what you're doing and the user context you need to operate under.
If you are writing scripts, programs or system integrations that leverage the ISC APIs, the OAuth 2.0 grant you should use typically depends on what you're doing and the user context you need to operate under.
Because scripts, code, and programs lack an interactive web-interface, it is difficult, but not impossible, to implement a working authorization code grant flow. System to system integrations may require an elevated level of access and utilize a service account to make API calls beyond the privileges of the authenticated user.
Most scripts, programs, and many integrations use the [Client Credentials grant flow](#request-access-token-with-client-credentials-grant-flow).
Using a PAT allows your API calls to work within a user context making client credentials ideal.
Most scripts, programs, and many integrations use the [Client Credentials grant flow](#request-access-token-with-client-credentials-grant-flow). Using a PAT allows your API calls to work within a user context making client credentials ideal.
## Troubleshooting
Having issues? Follow these steps:
Having issues? Follow these steps:
### Verify API endpoint calls
### Verify API endpoint calls
1. Verify the structure of the API call:
2. Verify that the API calls are going through the API gateway: `https://{tenant}.api.identitynow.com`
@@ -566,16 +535,15 @@ Having issues? Follow these steps:
:::info
You can also get a **403 Forbidden** response error when you call an API that expects a user, but your authorization grant type lacks a user context. Calling most admin APIs with a `CLIENT_CREDENTIAL` grant often produces this result.
You can also get a **403 Forbidden** response error when you call an API that expects a user, but your authorization grant type lacks a user context. Calling most admin APIs with a `CLIENT_CREDENTIAL` grant often produces this result.
:::
### Verify OAuth client
### Verify OAuth client
1. Verify that the OAuth 2.0 client is not a legacy OAuth client. Legacy OAuth clients will not work. This can become very apparent when you look at the client ID - OAuth 2.0 client IDs have dashes.
Here are two examples that illustrate the difference:
1. Verify that the OAuth 2.0 client is not a legacy OAuth client. Legacy OAuth clients will not work. This can become very apparent when you look at the client ID - OAuth 2.0 client IDs have dashes. Here are two examples that illustrate the difference:
Legacy Client ID: `G6xLlBBOKIcOAQuK`
Legacy Client ID: `G6xLlBBOKIcOAQuK`
OAuth 2.0 Client ID: `b61429f5-203d-494c-94c3-04f54e17bc5c`
@@ -611,10 +579,8 @@ You can also view all of the active clients in the UI by going to `https://{tena
}
```
4. If you're using an [Authorization Code](#authorization-code-grant-flow) grant flow, verify that the redirect URL(s) for your application match the `redirectUris` value in the client.
You can check this by calling the [List OAuth Clients endpoint](/docs/api/beta/list-oauth-clients).
4. If you're using an [Authorization Code](#authorization-code-grant-flow) grant flow, verify that the redirect URL(s) for your application match the `redirectUris` value in the client. You can check this by calling the [List OAuth Clients endpoint](/docs/api/beta/list-oauth-clients).
### Verify OAuth calls
Verify that the OAuth call flow is going to the right URLs, with the correct query parameters and data values.
A common source of errors is using the wrong host for authorization and token API calls.
The token endpoint URL is `{tenant}.api.identitynow.com`, while the authorize URL is `{tenant}.identitynow.com`.
Verify that the OAuth call flow is going to the right URLs, with the correct query parameters and data values. A common source of errors is using the wrong host for authorization and token API calls. The token endpoint URL is `{tenant}.api.identitynow.com`, while the authorize URL is `{tenant}.identitynow.com`.

52
docs/api/authorization.md
View File

@@ -5,10 +5,10 @@ pagination_label: Authorization
sidebar_label: Authorization
sidebar_position: 3
sidebar_class_name: authorization
keywords: ['authorization','scope','permission']
keywords: ['authorization', 'scope', 'permission']
description: Authorize your ISC API requests.
slug: /api/authorization
tags: ['Authorization','Scopes','Permissions']
tags: ['Authorization', 'Scopes', 'Permissions']
---
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
@@ -41,7 +41,7 @@ sequenceDiagram
## User Level Permissions
When managing a user's access to the API, you must first assign the target user an appropriate [user level](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html). It is important to choose the correct user level as it will place a boundary on which APIs a user can call, which also affects the areas and functions of the UI they have access to. For example, if a user is in charge of creating reports for auditing requirements, consider granting them the "Report Admin" user level.
When managing a user's access to the API, you must first assign the target user an appropriate [user level](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html). It is important to choose the correct user level as it will place a boundary on which APIs a user can call, which also affects the areas and functions of the UI they have access to. For example, if a user is in charge of creating reports for auditing requirements, consider granting them the "Report Admin" user level.
User levels are typically granted through the UI, [following the procedures from this document](https://documentation.sailpoint.com/saas/help/common/users/grant_remove_user_levels.html).
@@ -51,26 +51,26 @@ There is an [API that can set an identity's user level](https://developer.sailpo
:::
User levels act as the first line of defense by applying a rigid boundary around the APIs that a user can call. The next section introduces scopes, which allow users to apply granular controls on the APIs an access token can call.
User levels act as the first line of defense by applying a rigid boundary around the APIs that a user can call. The next section introduces scopes, which allow users to apply granular controls on the APIs an access token can call.
## Scopes
Scopes are granular permissions you can add to personal access tokens (PATs) to create tokens with the least privilege necessary to fulfill their functions. User levels place a broad border around the APIs a token has access to, while scopes can further limit the set of endpoints a token can call. Scopes allow an API user to have multiple tokens with different privileges that support unique use cases and software applications. Using scopes is beneficial to security - if a bad actor compromises any one of the tokens, the bad actor can only perform the limited set of operations defined by the token's scopes, significantly reducing the potential damage that can be done. Therefore, it is recommended that all users apply scopes to each PAT they create in order to reduce the impact of stolen credentials.
Scopes are granular permissions you can add to personal access tokens (PATs) to create tokens with the least privilege necessary to fulfill their functions. User levels place a broad border around the APIs a token has access to, while scopes can further limit the set of endpoints a token can call. Scopes allow an API user to have multiple tokens with different privileges that support unique use cases and software applications. Using scopes is beneficial to security - if a bad actor compromises any one of the tokens, the bad actor can only perform the limited set of operations defined by the token's scopes, significantly reducing the potential damage that can be done. Therefore, it is recommended that all users apply scopes to each PAT they create in order to reduce the impact of stolen credentials.
Scopes contain one or more rights, which are low level permissions that grant access to individual endpoints. This means that a single scope, like `idn:access-request:manage`, can grant access to multiple API endpoints. To determine which scopes a PAT needs, you must first identify which endpoints the PAT needs to invoke. Each endpoint's API specification indicates which scope is necessary to call the endpoint. You can use this approach to curate a list of scopes that must be applied to the credential to call the necessary endpoints. [Learn more about how to find an API's required scopes here](#identifying-necessary-authorization-for-an-endpoint).
Scopes contain one or more rights, which are low level permissions that grant access to individual endpoints. This means that a single scope, like `idn:access-request:manage`, can grant access to multiple API endpoints. To determine which scopes a PAT needs, you must first identify which endpoints the PAT needs to invoke. Each endpoint's API specification indicates which scope is necessary to call the endpoint. You can use this approach to curate a list of scopes that must be applied to the credential to call the necessary endpoints. [Learn more about how to find an API's required scopes here](#identifying-necessary-authorization-for-an-endpoint).
By default, each PAT has the scope `sp:scopes:default`, which is the least privileged scope. It only grants access to endpoints that require no authorization at all, such as [List Public Identities](https://developer.sailpoint.com/idn/api/v3/get-public-identities). Access to the endpoint may still be determined by the user's [user level](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html).
Alternatively, `sp:scopes:all` grants access to all the rights appropriate for the [user level](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html). For example, a user with the **Admin** user level has access to all APIs, so `sp:scopes:all` grants **Admin** users access to all APIs. A user with the **Cert Admin** user level, however, has access to only a subset of APIs necessary to perform their role, most notably the certification APIs, so `sp:scopes:all` grants **Cert Admin** users access to only that subset of APIs.
Scopes are additive, which means the final right set is the intersection of all the rights granted by the scopes assigned to a PAT, excluding any rights that fall outside of the user level. Each scope added to an PAT builds up the credential's permission set, incrementally increasing access to the API. If a PAT has `sp:scopes:all` granted, then any additional scope is ignored because `sp:scopes:all` already contains the complete set of rights available to the user level.
Scopes are additive, which means the final right set is the intersection of all the rights granted by the scopes assigned to a PAT, excluding any rights that fall outside of the user level. Each scope added to an PAT builds up the credential's permission set, incrementally increasing access to the API. If a PAT has `sp:scopes:all` granted, then any additional scope is ignored because `sp:scopes:all` already contains the complete set of rights available to the user level.
:::tip
If the API requirements for the personal access token exceed the scopes allowed by the user's assigned user level, then the following options may be considered.
- Re-evaluate the user's responsibilities compared to their user level. It is possible that their user level is no longer appropriate for the functions they need to perform, and a more permissive user level may be necessary.
- If the required access is a one-off need for a specific use case, then consider generating a PAT with the required scopes from a different user and sharing the credentials. This could be a dedicated service account designated for one-off applications. The downside of this approach is that it becomes more difficult to attribute an API call to a specific user, as the user now has a PAT that is not tied to their user account.
- Re-evaluate the user's responsibilities compared to their user level. It is possible that their user level is no longer appropriate for the functions they need to perform, and a more permissive user level may be necessary.
- If the required access is a one-off need for a specific use case, then consider generating a PAT with the required scopes from a different user and sharing the credentials. This could be a dedicated service account designated for one-off applications. The downside of this approach is that it becomes more difficult to attribute an API call to a specific user, as the user now has a PAT that is not tied to their user account.
:::
@@ -84,7 +84,7 @@ Each endpoint document specifies how to authorize with the endpoint in the **Aut
- **flow**: One or more OAuth flows supported by the endpoint. A token only needs to be generated by one flow to be valid. Refer to [Authentication Details](./authentication.md#authentication-details) for more information about the available flows.
- **scopes**: A list of scopes necessary to access the endpoint. A token only needs one of the scopes to authorize with the endpoint. When possible, choose the least privileged scope. Scopes ending in `read` can only retrieve data. Scopes ending in `manage` can retrieve, modify, and delete data.
You may also notice that many API descriptions will indicate the user level(s) required to call the API endpoint. In the screenshot above, the list access profiles endpoint requires the user to have one of the following user levels: ORG_ADMIN, ROLE_ADMIN, ROLE_SUBADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN. This means the PAT must have one of those user level **in addition to** the `sp:scopes:all` or `idn:access-profile:read` scope in order to call the endpoint.
You may also notice that many API descriptions will indicate the user level(s) required to call the API endpoint. In the screenshot above, the list access profiles endpoint requires the user to have one of the following user levels: ORG_ADMIN, ROLE_ADMIN, ROLE_SUBADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN. This means the PAT must have one of those user level **in addition to** the `sp:scopes:all` or `idn:access-profile:read` scope in order to call the endpoint.
:::info
@@ -106,11 +106,8 @@ Request Body
```json
{
"name": "Access Request and NELM Management",
"scope": [
"idn:access-request:manage",
"idn:nelm:manage"
]
"name": "Access Request and NELM Management",
"scope": ["idn:access-request:manage", "idn:nelm:manage"]
}
```
@@ -118,24 +115,21 @@ This request produces the following response, indicating that the scopes were su
```json
{
"id": "86286c0c456e4b03a8ccb1f892dd456d",
"name": "Access Request and NELM Management",
"secret": "********",
"scope": [
"idn:access-request:manage",
"idn:nelm:manage"
],
"created": "2023-01-04T18:58:17.486584Z",
"owner": {
"name": "jane.doe",
"id": "2c9180ab7624cbd7017642d8c8c81a73",
"type": "IDENTITY"
}
"id": "86286c0c456e4b03a8ccb1f892dd456d",
"name": "Access Request and NELM Management",
"secret": "********",
"scope": ["idn:access-request:manage", "idn:nelm:manage"],
"created": "2023-01-04T18:58:17.486584Z",
"owner": {
"name": "jane.doe",
"id": "2c9180ab7624cbd7017642d8c8c81a73",
"type": "IDENTITY"
}
}
```
:::caution
If you attempt to add a scope that is outside the permissions of the [target user's level](#user-level-permissions), the request will still succeed and include the invalid scope in the credentials. However, any token generated with these credentials will **not** include the rights of the invalid scope. This is not an issue when you apply scopes with the UI - the UI only shows scopes available to the current user.
If you attempt to add a scope that is outside the permissions of the [target user's level](#user-level-permissions), the request will still succeed and include the invalid scope in the credentials. However, any token generated with these credentials will **not** include the rights of the invalid scope. This is not an issue when you apply scopes with the UI - the UI only shows scopes available to the current user.
:::

4
docs/api/getting-started.md
View File

@@ -6,14 +6,14 @@ sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: gettingStarted
keywords: ['getting started']
description: Start using the ISC APIs.
description: Start using the ISC APIs.
slug: /api/getting-started
tags: ['Getting Started']
---
## Overview
This guide is intended to help you quickly make your first API call to SailPoint Identity Security Cloud and assumes an intermediate level of understanding of APIs. For beginners to APIs, we recommend you watch this presentation that covers the fundamentals of APIs with visual demonstrations of how to make an API call in SailPoint.
This guide is intended to help you quickly make your first API call to SailPoint Identity Security Cloud and assumes an intermediate level of understanding of APIs. For beginners to APIs, we recommend you watch this presentation that covers the fundamentals of APIs with visual demonstrations of how to make an API call in SailPoint.
<div class="text--center">
<iframe width="560" height="315" src="https://www.youtube.com/embed/YFRz8AcdWXg?si=9AvO6gMT1oCqYXAj" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

12
docs/api/identity-security-cloud.md
View File

@@ -6,14 +6,14 @@ sidebar_label: Identity Security Cloud API Specifications
sidebar_position: 1
sidebar_class_name: iscSpecifications
keywords: ['api', 'specifications']
description: ISC API specifications.
description: ISC API specifications.
slug: /api
tags: ['API Specifications']
---
## Overview
## Overview
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
@@ -22,8 +22,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).

4
docs/api/nerm/authentication.md
View File

@@ -11,8 +11,6 @@ slug: /api/nerm/authentication
tags: ['Authentication']
---
## Overview
NERM uses bearer tokens to allow customers to authenticate to NERM API endpoints. These tokens can be generated by following the instructions [here](https://documentation.sailpoint.com/ne-admin/help/setup/api.html).
@@ -20,5 +18,3 @@ NERM uses bearer tokens to allow customers to authenticate to NERM API endpoints
## Example
To use your bearer token simply provide it in the header with the request like so: `Authorization: Bearer <token>`

20
docs/api/nerm/pagination-metadata-filtering.md
View File

@@ -25,7 +25,7 @@ Use the following optional query parameters to achieve pagination:
| --- | --- | --- | --- |
| `limit` | Integer specifying the maximum number of records to return in a single API call. If it is not specified, a default limit is used. | `100` | Maxiumum of 500 for `api/profiles` |
| `offset` | Integer specifying the offset of the first result from the beginning of the collection. The **offset** value is record-based, not page-based, and the index starts at 0. For example, **offset=0** and **limit=20** returns records 0-19, but **offset=1** and **limit=20** returns records 1-20. | `0` | Between 0 and the last record index. |
| `order` | String specifying the ascending order in which the results should be returned, for example, **order=login** would return the users results in an ascending alphanumeric order| - | Limited to specific parameters |
| `order` | String specifying the ascending order in which the results should be returned, for example, **order=login** would return the users results in an ascending alphanumeric order | - | Limited to specific parameters |
Examples:
@@ -39,11 +39,12 @@ Metadata can be added to a result to allow for progromatic approaches to fetchin
| Name | Description | Default |
| --- | --- | --- |
| `metadata` | Boolean that specifies wether or not to return a **_metadata** key with pagination information | false |
| `metadata` | Boolean that specifies wether or not to return a **\_metadata** key with pagination information | false |
Example:
- GET `/api/users?metadata=true`
```
{
...
@@ -61,6 +62,7 @@ Example:
Resource attributes can be added to parameters to perform a basic match filter. Refer to each documented endpoints **Query Parameters** to identify what can be used.
Example:
- GET `/api/users?email=jim@acmeco.com`
## Advanced Profile Filtering
@@ -115,12 +117,12 @@ There are 3 types of **condition_rules_attributes**
This rule searches for profiles based on the status.
| Key | Type | Description |
|----------|------|-----------------------|
| --- | --- | --- |
| id | string | If you are updating an existing rule, include the ID of that rule, if you do not include an ID it will create a new condition rule |
| type | string **required** | The value must be 'ProfileStatusRule' |
| comparison_operator | string **required** | This is how the comparison is made for the attribute values. <br></br>Available basic operators: <ul><li>== (equals)</li><li>!= (not equal)</li></ul> |
| value | string **required** | This is the value used for comparison.0 <br></br>Available Values: <ul><li>Active</li><li>Inactive</li><li>Leave of absence</li><li>Terminated</li></ul> |
| _destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
| \_destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
Example:
@@ -143,12 +145,12 @@ Example:
This rule searches for profiles based on the id of the profile type.
| Key | Type | Description |
|----------|------|-----------------------|
| --- | --- | --- |
| id | string | If you are updating an existing rule, include the ID of that rule, if you do not include an ID it will create a new condition rule |
| type | string **required** | The value must be 'ProfileTypeRule' |
| comparison_operator | string **required** | This is how the comparison is made for the attribute values. Available basic operators: <ul><li>== (equals)</li><li>!= (not equal)</li></ul> |
| value | string **required** | This is the value used for comparison. This should be the ID of the profile type |
| _destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
| \_destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
Example:
@@ -171,14 +173,14 @@ Example:
This rule searches for profiles based on an attribute that profile has.
| Key | Type | Description |
|----------|------|-----------------------|
| --- | --- | --- |
| id | string | If you are updating an existing rule, include the ID of that rule, if you do not include an ID it will create a new condition rule |
| type | string **required** | The value must be 'ProfileAttributeRule' |
| object_type | string **required** | The values must equal 'NeAttribute' |
| condition_object_id | string **required** | this is the id of the attribute you are searching against |
| comparison_operator | string **required** | This is how the comparison is made for the attribute values. <br></br>Available basic operators: <ul><li>== (equals)</li><li>!= (not equal)</li><li>> (greater than)</li><li>< (less than)</li><li>start_with? (starts with)</li><li>end_with? (ends with)</li><li>include? (includes)</li></ul> Available date operators: <ul><li>before (before specific date)</li><li>after (after specific date)</li><li>> (more than X days before/after today)</li><li>< (less than X days before/after today)</li><li>== (equal to X days before/after today)</li></ul> |
| value | string **required** | This is the value used for comparison. <br></br>Value formatting: <ul><li>profile select attribute: ID of profile</li><li>profile search attribute: ID of profile</li><li>user select attribute: ID of user</li><li>user search attribute: ID of user</li><li>date attribute (before, after): correct date format for attribute</li><li>date attribute (>, <, ==): "X before" or "X after" where X is the number of days</li></ul> |
| _destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
| \_destroy | boolean | Supplying this option with "true" will cause the condition to be destroyed |
Example:
@@ -196,4 +198,4 @@ Example:
]
}
}
```
```

14
docs/api/non-employee.md
View File

@@ -6,16 +6,16 @@ sidebar_label: NERM API Specifications
sidebar_position: 1
sidebar_class_name: nermApiSpecifications
keywords: ['api', 'specifications']
description: NERM API specifications.
description: NERM API specifications.
slug: /api/nerm
tags: ['API Specifications']
---
## Overview
## Overview
[Non-Employee Risk Management (NERM)](https://documentation.sailpoint.com/ne-admin/help/) is an add-on to Identity Security Cloud (ISC) that helps organizations track non-employees such as contractors, partners, and vendors, and their lifecycles within the organization.
[Non-Employee Risk Management (NERM)](https://documentation.sailpoint.com/ne-admin/help/) is an add-on to Identity Security Cloud (ISC) that helps organizations track non-employees such as contractors, partners, and vendors, and their lifecycles within the organization.
The Non-Employee Risk Management (NERM) APIs provide developers with a way to interact with the NERM add-on and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
The Non-Employee Risk Management (NERM) APIs provide developers with a way to interact with the NERM add-on and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
@@ -24,8 +24,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the NERM APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tag/nerm).
To learn more about the NERM APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tag/nerm).

509
docs/api/patch-requests.md
View File

@@ -10,159 +10,145 @@ description: Send PATCH ISC API requests.
tags: ['patch', 'guide']
---
## PATCH requests
## PATCH requests
You can use the Identity Security Cloud APIs to update existing resources. Many of the APIs offer multiple ways to do so:
You can use the Identity Security Cloud APIs to update existing resources. Many of the APIs offer multiple ways to do so:
- You can send a **PUT** request to replace the existing resource with a new one. For example, if you wanted to update one of John Doe's source accounts, you could use the [Put Account](https://developer.sailpoint.com/docs/api/v3/put-account) endpoint to replace John Doe's existing source account with a new one. This is a viable way to update a resource, but it requires you to update the entire resource each time.
- You can send a **PUT** request to replace the existing resource with a new one. For example, if you wanted to update one of John Doe's source accounts, you could use the [Put Account](https://developer.sailpoint.com/docs/api/v3/put-account) endpoint to replace John Doe's existing source account with a new one. This is a viable way to update a resource, but it requires you to update the entire resource each time.
- You can send a **PATCH** request to make a specific change to the resource. For example, if you wanted to update John Doe's account's associated `identityId` attribute, you could use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to replace his existing `identityId` with a new one, all without affecting any of the other source account details. This can be very helpful when you want to make specific updates to resources, but it requires some knowledge of the types of changes, or "operations", that are possible, the specific paths of the fields you want to update, and some understanding of the basic data types.
- You can send a **PATCH** request to make a specific change to the resource. For example, if you wanted to update John Doe's account's associated `identityId` attribute, you could use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to replace his existing `identityId` with a new one, all without affecting any of the other source account details. This can be very helpful when you want to make specific updates to resources, but it requires some knowledge of the types of changes, or "operations", that are possible, the specific paths of the fields you want to update, and some understanding of the basic data types.
This guide will focus on the partial update method, PATCH requests. Read this guide to learn how to start sending PATCH requests.
This guide will focus on the partial update method, PATCH requests. Read this guide to learn how to start sending PATCH requests.
## Get the resource ID
To use PATCH to update a resource, you first need to know the resource ID.
To use PATCH to update a resource, you first need to know the resource ID.
Not all resource IDs are available in the Identity Security Cloud UI, so you may need to use the API to find the ID for the resource you want to update.
Not all resource IDs are available in the Identity Security Cloud UI, so you may need to use the API to find the ID for the resource you want to update.
For example, account IDs aren't avilable in the Identity Security Cloud UI. If you want to use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to make a change to a specific account, you first need to find out the account's ID.
For example, account IDs aren't avilable in the Identity Security Cloud UI. If you want to use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to make a change to a specific account, you first need to find out the account's ID.
You can use the [List Accounts](https://developer.sailpoint.com/docs/api/v3/list-accounts) endpoint to view all the accounts in your tenant, along with their details, such as their identities. You can find your account and its ID in this list.
You can use the [List Accounts](https://developer.sailpoint.com/docs/api/v3/list-accounts) endpoint to view all the accounts in your tenant, along with their details, such as their identities. You can find your account and its ID in this list.
## Get the resource details
## Get the resource details
Once you know the resource ID, you can use a GET request to get that resource's details. To successfully use a PATCH request to make changes to a resource, you need to know which paths you can update, what values they have, and the structure of those paths.
Once you know the resource ID, you can use a GET request to get that resource's details. To successfully use a PATCH request to make changes to a resource, you need to know which paths you can update, what values they have, and the structure of those paths.
For example, once you know the ID for the source you want to update with a PATCH request, you can use the [Get Source by ID](https://developer.sailpoint.com/docs/api/v3/get-source) endpoint to view only that source and its details.
For example, once you know the ID for the source you want to update with a PATCH request, you can use the [Get Source by ID](https://developer.sailpoint.com/docs/api/v3/get-source) endpoint to view only that source and its details.
In this example, the API returns a source, "ubuntu", along with all its details. This JSON response shows the resource's structure and its different paths:
In this example, the API returns a source, "ubuntu", along with all its details. This JSON response shows the resource's structure and its different paths:
<details>
<summary>Example Source Details</summary>
```json
{
"description": "ubuntu",
"owner": {
"type": "IDENTITY",
"id": "2c91808475b4334b0175e1e005006401",
"name": "SailPoint Services"
"description": "ubuntu",
"owner": {
"type": "IDENTITY",
"id": "2c91808475b4334b0175e1e005006401",
"name": "SailPoint Services"
},
"cluster": null,
"accountCorrelationConfig": null,
"accountCorrelationRule": null,
"managerCorrelationMapping": null,
"managerCorrelationRule": null,
"beforeProvisioningRule": null,
"schemas": [
{
"type": "CONNECTOR_SCHEMA",
"id": "2c91808c771b686101772a91dbd877ab",
"name": "account"
},
"cluster": null,
"accountCorrelationConfig": null,
"accountCorrelationRule": null,
"managerCorrelationMapping": null,
"managerCorrelationRule": null,
"beforeProvisioningRule": null,
"schemas": [
{
"type": "CONNECTOR_SCHEMA",
"id": "2c91808c771b686101772a91dbd877ab",
"name": "account"
},
{
"type": "CONNECTOR_SCHEMA",
"id": "2c91808c771b686101772a91dbd877ac",
"name": "group"
}
],
"passwordPolicies": null,
"features": [
"NO_RANDOM_ACCESS",
"DISCOVER_SCHEMA",
"DIRECT_PERMISSIONS"
],
"type": "DelimitedFile",
"connector": "delimited-file-angularsc",
"connectorClass": "sailpoint.connector.DelimitedFileConnector",
"connectorAttributes": {
"mergeColumns": [
"groups"
],
"group.mergeRows": true,
"group.delimiter": ",",
"mergeRows": true,
"group.filetransport": "local",
"partitionMode": "disabled",
"connectionType": "file",
"group.host": "local",
"group.indexColumn": "id",
"file": "/tmp/source-account-2c91808c771b686101772a91dbd877aa3299228430527475607.csv",
"delimiter": ",",
"deltaAggregation": null,
"host": "local",
"cloudExternalId": "23012",
"group.indexColumns": [
"id"
],
"cloudIdentityProfileName": null,
"group.mergeColumns": [
"entitlements",
"groups",
"permissions"
],
"hasHeader": true,
"filterEmptyRecords": true,
"oauth_body_attrs_to_exclude": "client_secret,client_id",
"filetransport": "local",
"idnPreviousCorrelationConfig": null,
"deleteThresholdPercentage": 10,
"group.filterEmptyRecords": true,
"group.hasHeader": true,
"group.partitionMode": "disabled",
"cloudAuthoritativeSourcePrecedence": null,
"formPath": null,
"group.columnNames": [
"id",
"name",
"displayName",
"created",
"description",
"modified",
"entitlements",
"groups",
"permissions"
],
"templateApplication": "DelimitedFile Template",
"group.file": "/var/lib/identityiq_workspace/27c92c24-8681-4574-9453-5c56370b3fc9-groups.csv",
"indexColumn": "id",
"healthy": false,
"cloudDisplayName": "Ubuntu",
"connectorName": "Delimited File",
"beforeProvisioningRule": null,
"cloudOriginalApplicationType": "Delimited File",
"since": "2021-01-22T14:48:58.072Z",
"status": "SOURCE_STATE_ERROR_ACCOUNT_FILE_IMPORT"
},
"deleteThreshold": 10,
"authoritative": false,
"healthy": false,
"status": "SOURCE_STATE_ERROR_ACCOUNT_FILE_IMPORT",
"since": "2021-01-22T14:48:58.072Z",
"connectorId": "delimited-file",
"connectorName": "Delimited File",
{
"type": "CONNECTOR_SCHEMA",
"id": "2c91808c771b686101772a91dbd877ac",
"name": "group"
}
],
"passwordPolicies": null,
"features": ["NO_RANDOM_ACCESS", "DISCOVER_SCHEMA", "DIRECT_PERMISSIONS"],
"type": "DelimitedFile",
"connector": "delimited-file-angularsc",
"connectorClass": "sailpoint.connector.DelimitedFileConnector",
"connectorAttributes": {
"mergeColumns": ["groups"],
"group.mergeRows": true,
"group.delimiter": ",",
"mergeRows": true,
"group.filetransport": "local",
"partitionMode": "disabled",
"connectionType": "file",
"connectorImplementationId": "delimited-file",
"managementWorkgroup": null,
"id": "2c91808c771b686101772a91dbd877aa",
"name": "Ubuntu",
"created": "2021-01-22T14:48:58.072Z",
"modified": "2023-06-30T13:39:07.456Z"
"group.host": "local",
"group.indexColumn": "id",
"file": "/tmp/source-account-2c91808c771b686101772a91dbd877aa3299228430527475607.csv",
"delimiter": ",",
"deltaAggregation": null,
"host": "local",
"cloudExternalId": "23012",
"group.indexColumns": ["id"],
"cloudIdentityProfileName": null,
"group.mergeColumns": ["entitlements", "groups", "permissions"],
"hasHeader": true,
"filterEmptyRecords": true,
"oauth_body_attrs_to_exclude": "client_secret,client_id",
"filetransport": "local",
"idnPreviousCorrelationConfig": null,
"deleteThresholdPercentage": 10,
"group.filterEmptyRecords": true,
"group.hasHeader": true,
"group.partitionMode": "disabled",
"cloudAuthoritativeSourcePrecedence": null,
"formPath": null,
"group.columnNames": [
"id",
"name",
"displayName",
"created",
"description",
"modified",
"entitlements",
"groups",
"permissions"
],
"templateApplication": "DelimitedFile Template",
"group.file": "/var/lib/identityiq_workspace/27c92c24-8681-4574-9453-5c56370b3fc9-groups.csv",
"indexColumn": "id",
"healthy": false,
"cloudDisplayName": "Ubuntu",
"connectorName": "Delimited File",
"beforeProvisioningRule": null,
"cloudOriginalApplicationType": "Delimited File",
"since": "2021-01-22T14:48:58.072Z",
"status": "SOURCE_STATE_ERROR_ACCOUNT_FILE_IMPORT"
},
"deleteThreshold": 10,
"authoritative": false,
"healthy": false,
"status": "SOURCE_STATE_ERROR_ACCOUNT_FILE_IMPORT",
"since": "2021-01-22T14:48:58.072Z",
"connectorId": "delimited-file",
"connectorName": "Delimited File",
"connectionType": "file",
"connectorImplementationId": "delimited-file",
"managementWorkgroup": null,
"id": "2c91808c771b686101772a91dbd877aa",
"name": "Ubuntu",
"created": "2021-01-22T14:48:58.072Z",
"modified": "2023-06-30T13:39:07.456Z"
}
```
</details>
## PATCH request structure
## PATCH request structure
A PATCH request involves sending a JSON PATCH document that represents an array of objects. Each object represents a single operation to be applied to the target resource.
A PATCH request involves sending a JSON PATCH document that represents an array of objects. Each object represents a single operation to be applied to the target resource.
PATCH requests all share the same essential structure. A PATCH request must include an object that specifies exactly one operation to apply to update the resource, as well as exactly one path that represents the target location where the operation is applied.
PATCH requests all share the same essential structure. A PATCH request must include an object that specifies exactly one operation to apply to update the resource, as well as exactly one path that represents the target location where the operation is applied.
This example request has the basic PATCH structure:
This example request has the basic PATCH structure:
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
@@ -176,31 +162,29 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
"value": "new description"
}
]
```
This example request uses a "replace" operation to replace the source's existing description with a new value, "new description". This example shows the parts involved in sending a PATCH request. You must specify an operation to apply to the target resource, a path to apply the operation to, and the change you want to make, often in the form of a value or a "from" location for "copy" and "move" operations.
This example request uses a "replace" operation to replace the source's existing description with a new value, "new description". This example shows the parts involved in sending a PATCH request. You must specify an operation to apply to the target resource, a path to apply the operation to, and the change you want to make, often in the form of a value or a "from" location for "copy" and "move" operations.
You can find this example in the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification. The API specifications have examples on the right side of the page that you can copy and use to get started. You can tab between the different examples to see a variety of pre-built requests you can use.
You can find this example in the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification. The API specifications have examples on the right side of the page that you can copy and use to get started. You can tab between the different examples to see a variety of pre-built requests you can use.
A PATCH request can be more complex as well - the values can be simple or vast and detailed. You can use a PATCH request to apply multiple operations, with a path for each, or you can apply the same type of operation to multiple paths. The PATCH request will always have the same essential structure though.
A PATCH request can be more complex as well - the values can be simple or vast and detailed. You can use a PATCH request to apply multiple operations, with a path for each, or you can apply the same type of operation to multiple paths. The PATCH request will always have the same essential structure though.
:::note
The ordering of members in JSON objects doesn't affect the response. These examples all specify the operation first, but you would get the same response if you specified the members in any other order.
The ordering of members in JSON objects doesn't affect the response. These examples all specify the operation first, but you would get the same response if you specified the members in any other order.
:::
You can specify a single operation, or you can specify multiple. If you are using multiple operations in one PATCH request, each operation must include its own path.
You can specify a single operation, or you can specify multiple. If you are using multiple operations in one PATCH request, each operation must include its own path.
This example request applies "replace" and "add" ops to different paths:
This example request applies "replace" and "add" ops to different paths:
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
```
```json
[
{
"op": "replace",
@@ -213,116 +197,108 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
"value": "!( id.contains( \"m\" ) ) || !( id.contains( \"d\" ) )"
}
]
```
This example request uses a "replace" to update the source's description and an "add" to add a filter string to the source's connector.
This example request uses a "replace" to update the source's description and an "add" to add a filter string to the source's connector.
## Specify an operation
## Specify an operation
Once you know the ID of the resource you want to update and you have the resource's details, you can start writing your PATCH request.
Once you know the ID of the resource you want to update and you have the resource's details, you can start writing your PATCH request.
The first step is to specify an operation to apply to the target resource.
The first step is to specify an operation to apply to the target resource.
Operation objects must have exactly one "op" member, whose value indicates the operation to perform.
Operation objects must have exactly one "op" member, whose value indicates the operation to perform.
These are the available PATCH operations:
These are the available PATCH operations:
- [Add](#add)
- [Remove](#remove)
- [Replace](#replace)
- [Move](#move)
- [Copy](#copy)
- [Copy](#copy)
- [Test](#test)
### Add
### Add
The "add" operation adds a value to the target location. For more information about the "add" operation and how it behaves in different scenarios, refer to the [JSON PATCH documentation](https://datatracker.ietf.org/doc/html/rfc6902).
The "add" operation adds a value to the target location. For more information about the "add" operation and how it behaves in different scenarios, refer to the [JSON PATCH documentation](https://datatracker.ietf.org/doc/html/rfc6902).
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to add a new "office" attribute to the end of a source schema's array of attributes:
```json
[
{
"op": "add",
"path": "/attributes/-",
"value":
{
"name": "office",
"type": "STRING",
"schema": null,
"description": "Office Location",
"isMulti": false,
"isEntitlement": false,
"op": "add",
"path": "/attributes/-",
"value": {
"name": "office",
"type": "STRING",
"schema": null,
"description": "Office Location",
"isMulti": false,
"isEntitlement": false,
"isGroup": false
}
}
]
```
If you are adding a new value to an array of values, you can specify the position within the array where you want to add the new value. In this example, using the "-" expression at the end of the path specifies that the new attribute will be added to the end of the array of attributes.
If you are adding a new value to an array of values, you can specify the position within the array where you want to add the new value. In this example, using the "-" expression at the end of the path specifies that the new attribute will be added to the end of the array of attributes.
You can use "0" to add a value to the beginning of the array. You can use "1" to add a value to the second positon, and so on. Using "-" adds the value to the end of the array.
You can use "0" to add a value to the beginning of the array. You can use "1" to add a value to the second positon, and so on. Using "-" adds the value to the end of the array.
### Remove
### Remove
The "remove" operation removes a value from the target location. The target location must exist for the operation to be successful.
The "remove" operation removes a value from the target location. The target location must exist for the operation to be successful.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to remove an existing filter string from a source's connector:
```json
[
[
{
"op": "remove",
"path": "/connectorAttributes/filterString"
"op": "remove",
"path": "/connectorAttributes/filterString"
}
]
```
]
```
In this example, the PATCH request is removing a connector's string filter. If there is no string filter to remove, the request will fail and you will receive an error.
In this example, the PATCH request is removing a connector's string filter. If there is no string filter to remove, the request will fail and you will receive an error.
Because there is only one value for the path, the request removes that value.
Because there is only one value for the path, the request removes that value.
If there is an array of values, you must specify the position within the array to remove that value.
If there is an array of values, you must specify the position within the array to remove that value.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to remove the first feature from a source's list of features.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to remove the first feature from a source's list of features.
The source has three features, "ENABLE", "PROVISIONING", AND "UNLOCK".
The source has three features, "ENABLE", "PROVISIONING", AND "UNLOCK".
This request will remove the the first value from the list, "ENABLE".
This request will remove the the first value from the list, "ENABLE".
```json
[
{
"op": "remove",
"op": "remove",
"path": "/features/0"
}
]
]
```
### Replace
### Replace
The "replace" operation replaces the value at the target location with a new value. The operation object must contain a "value" member whose content specifies the replacement value, and the target location must exist for the operation to be successful. This operation is the equivalent of a "remove" followed by an "add".
The "replace" operation replaces the value at the target location with a new value. The operation object must contain a "value" member whose content specifies the replacement value, and the target location must exist for the operation to be successful. This operation is the equivalent of a "remove" followed by an "add".
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace a source's existing features with new ones:
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace a source's existing features with new ones:
```json
[
{
"op": "replace",
"path": "/features",
"value":
[
"PASSWORD",
"PROVISIONING",
"ENABLE",
"AUTHENTICATE"
]
"op": "replace",
"path": "/features",
"value": ["PASSWORD", "PROVISIONING", "ENABLE", "AUTHENTICATE"]
}
]
]
```
You can also replace a value within an array. This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace the first value in the array with the specified value:
You can also replace a value within an array. This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace the first value in the array with the specified value:
```json
[
@@ -334,71 +310,65 @@ You can also replace a value within an array. This example uses the [Patch Sourc
]
```
This request removes the first feature ("PASSWORD") in the list and adds the "CURRENT_PASSWORD" value in its place.
This request removes the first feature ("PASSWORD") in the list and adds the "CURRENT_PASSWORD" value in its place.
### Move
The "move" operation removes the operation from a specified location and adds it to the target location. This operation object must contain a "from" member whose content specifies the location to remove the value from, and the "from" location must exist for the operation to be successful.
The "move" operation removes the operation from a specified location and adds it to the target location. This operation object must contain a "from" member whose content specifies the location to remove the value from, and the "from" location must exist for the operation to be successful.
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute from the beginning to the end of the schema's array of attributes:
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute from the beginning to the end of the schema's array of attributes:
```json
```json
[
{
"op": "move",
"from": "/attributes/0",
"op": "move",
"from": "/attributes/0",
"path": "/attributes/-"
}
]
```
### Copy
The "copy" operation copies the value from a specified location to the target location. The operation object must contain a "from" member whose content specifies the location to copy the value from, and the "from" location must exist for the operation to be successful.
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to copies an attribute from the beginning and duplicates it at the end of the schema's array of attributes:
```json
[
{
"op": "copy",
"from": "/attributes/0",
"path": "/attributes/-"
}
]
```
### Test
The "test" operation is unique in that it does not apply changes to the resource. The "test" operation tests that a value at the target location is equal to a specified value. The operation object must contain a "value" member whose content specifies the value to be compared to the target location's value, and the values must be equal for the operation to be successful. For more information about what "equal" means for different JSON types, refer [here](https://datatracker.ietf.org/doc/html/rfc6902#section-4.6).
The "test" operation allows you to check that a resource has the values you expect it to have, and then you can make changes to those values from there with another PATCH request.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to test a source's existing features to make sure they match the specified values.:
```json
[
{
"op": "test",
"path": "/features",
"value":
[
"PASSWORD",
"PROVISIONING",
"ENABLE",
"AUTHENTICATE"
]
}
]
```
## Specify a path
### Copy
Once you have specified the operation you want to apply to the target resource, you must specify the path, the JSON Pointer for the target location that you want to apply the operation to.
The "copy" operation copies the value from a specified location to the target location. The operation object must contain a "from" member whose content specifies the location to copy the value from, and the "from" location must exist for the operation to be successful.
To send a PATCH request, you must know the path where you want to make the change. This is why it's important to get the resource's details so that you can see all the resource's available paths where you can make changes.
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to copies an attribute from the beginning and duplicates it at the end of the schema's array of attributes:
For example, this snippet from the beginning of the earlier source details example lists many of the source's top-level paths:
```json
[
{
"op": "copy",
"from": "/attributes/0",
"path": "/attributes/-"
}
]
```
### Test
The "test" operation is unique in that it does not apply changes to the resource. The "test" operation tests that a value at the target location is equal to a specified value. The operation object must contain a "value" member whose content specifies the value to be compared to the target location's value, and the values must be equal for the operation to be successful. For more information about what "equal" means for different JSON types, refer [here](https://datatracker.ietf.org/doc/html/rfc6902#section-4.6).
The "test" operation allows you to check that a resource has the values you expect it to have, and then you can make changes to those values from there with another PATCH request.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to test a source's existing features to make sure they match the specified values.:
```json
[
{
"op": "test",
"path": "/features",
"value": ["PASSWORD", "PROVISIONING", "ENABLE", "AUTHENTICATE"]
}
]
```
## Specify a path
Once you have specified the operation you want to apply to the target resource, you must specify the path, the JSON Pointer for the target location that you want to apply the operation to.
To send a PATCH request, you must know the path where you want to make the change. This is why it's important to get the resource's details so that you can see all the resource's available paths where you can make changes.
For example, this snippet from the beginning of the earlier source details example lists many of the source's top-level paths:
<details>
<summary>Example Source Paths</summary>
@@ -439,7 +409,7 @@ For example, this snippet from the beginning of the earlier source details examp
</details>
You can send PATCH requests to make changes to some of these paths, like editing the source's description with this PATCH request from earlier:
You can send PATCH requests to make changes to some of these paths, like editing the source's description with this PATCH request from earlier:
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
@@ -455,9 +425,9 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
]
```
However, you cannot make changes to all paths. Use the API specifications for the PATCH endpoint you want to use to find out which paths you can make changes to. The API specifications will list the paths, or fields, that are immutable, if there are any. For example, the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification lists paths like `id` and `type` as being immutable. Trying to use modify these paths results in a 400 error.
However, you cannot make changes to all paths. Use the API specifications for the PATCH endpoint you want to use to find out which paths you can make changes to. The API specifications will list the paths, or fields, that are immutable, if there are any. For example, the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification lists paths like `id` and `type` as being immutable. Trying to use modify these paths results in a 400 error.
The paths are often nested within other paths, like within the "connectorAttributes" path from the earlier example source's details:
The paths are often nested within other paths, like within the "connectorAttributes" path from the earlier example source's details:
<details>
<summary>Example Source Connector Attributes</summary>
@@ -527,7 +497,7 @@ The paths are often nested within other paths, like within the "connectorAttribu
</details>
You can send a PATCH request to make changes to paths within the "connectorAttributes" path itself. This example request removes the "filterString" path and its value.
You can send a PATCH request to make changes to paths within the "connectorAttributes" path itself. This example request removes the "filterString" path and its value.
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
@@ -543,19 +513,19 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
]
```
This request specifies the top-level path, "connectorAttributes", following it with the path where the value is going to be removed from, "filterString".
This request specifies the top-level path, "connectorAttributes", following it with the path where the value is going to be removed from, "filterString".
The request will only remove a filter string matching the one specified, so any other filter strings or connector attributes will be unaffected.
The request will only remove a filter string matching the one specified, so any other filter strings or connector attributes will be unaffected.
If there is no value matching the filter string specified by the PATCH request, the request will fail and you will receive an error.
If there is no value matching the filter string specified by the PATCH request, the request will fail and you will receive an error.
## Specify a value
## Specify a value
For many of the operations, once you have specified the operation you want to apply and the path you want to apply it to, you need to specify the value you want to send with the request. The value you specify must fit the path's data type.
For many of the operations, once you have specified the operation you want to apply and the path you want to apply it to, you need to specify the value you want to send with the request. The value you specify must fit the path's data type.
The operations that don't require a value are the "copy" and "move" operations. Those operations instead use a "from" to represent the location they are copying or moving the data from. Refer to the [Specify a From](#specify-a-from) section for more information about how to use "from" with your "copy" and "move" operations.
The operations that don't require a value are the "copy" and "move" operations. Those operations instead use a "from" to represent the location they are copying or moving the data from. Refer to the [Specify a From](#specify-a-from) section for more information about how to use "from" with your "copy" and "move" operations.
You can specify a single simple value for an operation. In this example from earlier, the PATCH request replaces the source's description:
You can specify a single simple value for an operation. In this example from earlier, the PATCH request replaces the source's description:
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
@@ -571,7 +541,7 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
]
```
You can also specify multiple values for an operation to be applied to, as long as they all affect the same path. For example, this PATCH request replaces the source's current features with a number of new ones:
You can also specify multiple values for an operation to be applied to, as long as they all affect the same path. For example, this PATCH request replaces the source's current features with a number of new ones:
```text
PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
@@ -582,17 +552,12 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
{
"op": "replace",
"path": "/features",
"value": [
"PASSWORD",
"PROVISIONING",
"ENABLE",
"AUTHENTICATE"
]
"value": ["PASSWORD", "PROVISIONING", "ENABLE", "AUTHENTICATE"]
}
]
```
A value can also be an object that contains other values within it. For example, this PATCH request adds a new "location" attribute to the end of the source schema's array of attributes:
A value can also be an object that contains other values within it. For example, this PATCH request adds a new "location" attribute to the end of the source schema's array of attributes:
```text
PATCH https://{tenant}.api.identitynow.com//v3/sources/:sourceId/schemas/:schemaId
@@ -616,50 +581,48 @@ PATCH https://{tenant}.api.identitynow.com//v3/sources/:sourceId/schemas/:schema
]
```
This request uses the [PATCH Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to add a new attribute, along with its details, to the end of the array of a source's schema's attributes.
This request uses the [PATCH Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to add a new attribute, along with its details, to the end of the array of a source's schema's attributes.
This example uses the "-" after the path to indicate that the value will be added to the end of the array. When you are adding a new value to an array of values, you can specify the position within the array where you want to add the new value. In this example, using the "-" expression at the end of the path specifies that the new attribute will be added to the end of the array of attributes.
This example uses the "-" after the path to indicate that the value will be added to the end of the array. When you are adding a new value to an array of values, you can specify the position within the array where you want to add the new value. In this example, using the "-" expression at the end of the path specifies that the new attribute will be added to the end of the array of attributes.
You can use "0" to add a value to the beginning of the array. You can use "1" to add a value to the second positon, and so on. Using "-" adds the value to the end of the array.
You can use "0" to add a value to the beginning of the array. You can use "1" to add a value to the second positon, and so on. Using "-" adds the value to the end of the array.
## Specify a from
## Specify a from
The "move" and "copy" operations allow you to remove or copy information from one path and add it to another path without your needing to specify the value, which could be an extensive array of information. To use the "move" and "copy" operations, you must specify a "from", a JSON Pointer representing the location you are moving or copying the value from.
The "move" and "copy" operations allow you to remove or copy information from one path and add it to another path without your needing to specify the value, which could be an extensive array of information. To use the "move" and "copy" operations, you must specify a "from", a JSON Pointer representing the location you are moving or copying the value from.
This example request uses the [PATCH Source schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute, along with its details, from the beginning to the end of a source schema's array of attributes:
This example request uses the [PATCH Source schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute, along with its details, from the beginning to the end of a source schema's array of attributes:
```text
PATCH https://{tenant}.api.identitynow.com//v3/sources/:sourceId/schemas/:schemaId
```
```json
[
[
{
"op": "move",
"from": "/attributes/0",
"op": "move",
"from": "/attributes/0",
"path": "/attributes/-"
}
]
}
]
```
```
Instead of having to specify the value yourself, which could be an extensive array of information, you can use the "move" operation to move everything from one path to another.
Instead of having to specify the value yourself, which could be an extensive array of information, you can use the "move" operation to move everything from one path to another.
## Apply the PATCH request header
With an operation, a path, and a change to make, a PATCH request is almost ready.
With an operation, a path, and a change to make, a PATCH request is almost ready.
To send the request as a PATCH, you must apply this special PATCH content type header: `Content-Type: application/json-patch+json`
## Send your PATCH request
## Send your PATCH request
Once you have specified the operation you want to apply, the path you want to change, the change you want to make, and you have applied the PATCH content type header, you can send your PATCH request.
Once you have specified the operation you want to apply, the path you want to change, the change you want to make, and you have applied the PATCH content type header, you can send your PATCH request.
When the request is successful, the API will return the updated resource.
When the request is successful, the API will return the updated resource.
## Get started
## Get started
Now you can use PATCH requests partially update resources. For more information about PATCH requests, refer to this [documentation](https://datatracker.ietf.org/doc/html/rfc6902). For more information about the Identity Security Cloud PATCH endpoints and which paths can be changed for each one, refer to their API specifications.
Now you can use PATCH requests partially update resources. For more information about PATCH requests, refer to this [documentation](https://datatracker.ietf.org/doc/html/rfc6902). For more information about the Identity Security Cloud PATCH endpoints and which paths can be changed for each one, refer to their API specifications.
Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!
Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!

11
docs/api/postman-collections.md
View File

@@ -6,11 +6,10 @@ sidebar_label: Postman Collections
sidebar_position: 7
sidebar_class_name: postmanCollections
keywords: ['postman']
description: Run ISC APIs in Postman.
description: Run ISC APIs in Postman.
tags: ['postman']
---
import GitHubPublicFileComponent from '@site/src/components/GitHubLink';
[Postman](https://www.postman.com/) is a platform you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the Identity Security Cloud API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the ISC API collections and stay up to date.
@@ -19,10 +18,8 @@ import GitHubPublicFileComponent from '@site/src/components/GitHubLink';
Each ISC API version is broken out into a separate collection within the workspace. The following table lists the available ISC API collections. To import a collection into your workspace, select the 'Run in Postman' button for your desired version. Doing so forks the collection into your workspace.
| API | Postman Collection |
|------|----------------------------|
| --- | --- |
| V3 API | [![Run in Postman](./img/button.svg)](https://god.gw.postman.com/run-collection/23226990-3721beea-5615-44b4-9459-e858a0ca7aed?action=collection%2Ffork&collection-url=entityId%3D23226990-3721beea-5615-44b4-9459-e858a0ca7aed%26entityType%3Dcollection%26workspaceId%3D80af54be-a333-4712-af5e-41aa9eccbdd0) |
| Beta API | [![Run in Postman](./img/button.svg)](https://god.gw.postman.com/run-collection/23226990-3b87172a-cd55-40a2-9ace-1560a1158a4e?action=collection%2Ffork&collection-url=entityId%3D23226990-3b87172a-cd55-40a2-9ace-1560a1158a4e%26entityType%3Dcollection%26workspaceId%3D80af54be-a333-4712-af5e-41aa9eccbdd0) |
| NERM API | [![Run in Postman](./img/button.svg)](https://god.gw.postman.com/run-collection/23226990-20d718e3-b9b3-43ad-850c-637b00864ae2?action=collection%2Ffork&collection-url=entityId%3D23226990-20d718e3-b9b3-43ad-850c-637b00864ae2%26entityType%3Dcollection%26workspaceId%3D80af54be-a333-4712-af5e-41aa9eccbdd0) |
@@ -41,12 +38,12 @@ SailPoint is often making improvements to the ISC API collections. To keep your
The SailPoint workspace provides an environment, a set of variables you can use in your requests, that you can fork and pull changes from to stay up to date the same way you can with collections. To import the environment into your workspace, select 'Run in Postman'.
| Environment | [![Run in Postman](./img/button.svg)](https://www.postman.com/sailpoint/workspace/identitynow/environment/23226990-ed571d4f-37a3-4a2c-9105-5d8d8cce1d20/fork) |
|------|----------------------------|
| --- | --- |
To send API requests in Postman, you must authenticate to the APIs. To authenticate to the APIs, you must specify these variables in your Postman environment:
| Environment Variable | Required | Description |
| ----------- | ----------- | ----------- |
| --- | --- | --- |
| tenant | Yes | Your ISC tenant, typically your company's name |
| clientId | Yes | The client ID for the API client or personal access token |
| clientSecret | Yes | The client secret for the API client or personal access token |

2
docs/api/rate-limit.md
View File

@@ -6,7 +6,7 @@ sidebar_label: Rate Limiting
sidebar_position: 6
sidebar_class_name: rateLimit
keywords: ['rate limit']
description: ISC API rate limits.
description: ISC API rate limits.
tags: ['Rate Limit']
---

40
docs/api/standard-collection-parameters.md
View File

@@ -6,7 +6,7 @@ sidebar_label: Standard Collection Parameters
sidebar_position: 5
sidebar_class_name: standardCollectionParameters
keywords: ['standard collection parameters']
description: ISC API pagination, filtering, and sorting.
description: ISC API pagination, filtering, and sorting.
tags: ['Standard Collection Parameters']
---
@@ -40,11 +40,11 @@ The `searchAfter` capability provides the ability to page on sorted field values
**Required Properties for Paginating Search Results**
|**Property**|Description|
| **Property** | Description |
| --- | --- |
|**query**|The Query JSON object. Refer to the following Query JSON Object table for details.|
|**sort**|The array list of the fields to sort by. This is required if you are using the `searchAfter` approach. You can use `-fieldName` for descending searches (optional).|
|**searchAfter**|You can use this instead of offset to get past the 10,000 paging result record limit, passing the last value(s) of your sort fields from the previous result set into the next result set until you get the total number of results or the end of results (optional).|
| **query** | The Query JSON object. Refer to the following Query JSON Object table for details. |
| **sort** | The array list of the fields to sort by. This is required if you are using the `searchAfter` approach. You can use `-fieldName` for descending searches (optional). |
| **searchAfter** | You can use this instead of offset to get past the 10,000 paging result record limit, passing the last value(s) of your sort fields from the previous result set into the next result set until you get the total number of results or the end of results (optional). |
### Example of Paginating Search Results
@@ -54,15 +54,11 @@ Here is an example of a search API call with `searchAfter` paging. The first que
```json
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"id"
]
"indices": ["identities"],
"query": {
"query": "*"
},
"sort": ["id"]
}
```
@@ -72,16 +68,12 @@ This query will return 100 records. To get the next 100 records, find the last r
```json
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"id"
],
"searchAfter": ["2c9180835d38ca0c015d606b50851b1e"]
"indices": ["identities"],
"query": {
"query": "*"
},
"sort": ["id"],
"searchAfter": ["2c9180835d38ca0c015d606b50851b1e"]
}
```