Merge branch 'main' into DEVREL-1689

This commit is contained in:
christina-gagnon-sp
2024-07-23 10:36:28 -07:00
committed by GitHub
524 changed files with 25452 additions and 5919 deletions

View File

@@ -68,8 +68,8 @@ To authenticate to the ISC APIs, you must be able to connect to your tenant to s
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:
@@ -100,7 +100,7 @@ A personal access token (PAT) is a method of authenticating to an API as a user
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`
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.
@@ -130,7 +130,7 @@ There are several different authorization flows that OAuth 2.0 supports, and eac
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.
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 can only be 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):
@@ -170,7 +170,7 @@ 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
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):
@@ -182,22 +182,22 @@ This example shows how to pass the information with form-data in the request bod
- 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}}
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
- 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:
| Key | Description |
| --- | --- |
| `grant_type` | This is set to `CLIENT_CREDENTIALS` for the authorization code grant type. |
| `client_id` | This is the API client's ID (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). You can generate this ID at `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`, or you can generate it when you create a PAT. |
| `client_secret` | This is the API client's secret describing (e.g. `c924417c85b19eda40e171935503d8e9747ca60ddb9b48ba4c6bb5a7145fb6c5`). You can generate this secret at `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`, or you can generate it when you create a PAT. |
| `client_id` | This is the API client's ID (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). You can generate this ID at `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`, or you can generate it when you create a PAT. |
| `client_secret` | This is the API client's secret describing (e.g. `c924417c85b19eda40e171935503d8e9747ca60ddb9b48ba4c6bb5a7145fb6c5`). You can generate this secret at `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`, or you can generate it when you create a PAT. |
This example cURL command passes client credentials in the body as form-data to generate an access token:
```bash
curl --location 'https://{tenant}.api.identitynow.com/oauth/token' \
curl --location 'https://[tenant].api.identitynow.com/oauth/token' \
--header 'scope: sp:scope:all' \
--form 'grant_type="client_credentials"' \
--form 'client_id="{clientId}"' \
@@ -251,11 +251,11 @@ sequenceDiagram
participant I as Identity Security Cloud
U->>W: Click login link
W->>I: Authorization request to https://{tenant}.login.sailpoint.com/oauth/authorize
W->>I: Authorization request to https://[tenant].login.sailpoint.com/oauth/authorize
I->>U: Redirect to login prompt
U->>I: Authentication
I->>W: Authorization code granted
W->>I: Authorization code to https://{tenant}.api.identitynow.com/oauth/token
W->>I: Authorization code to https://[tenant].api.identitynow.com/oauth/token
I->>W: JWT access token granted
```
@@ -268,7 +268,7 @@ This is the overall authorization flow:
2. The web app sends an authorization request to ISC in this form:
```Text
GET https://{tenant}.login.sailpoint.com/oauth/authorize?client_id={client-id}&response_type=code&redirect_uri={redirect-url}
GET https://[tenant].login.sailpoint.com/oauth/authorize?client_id={client-id}&response_type=code&redirect_uri={redirect-url}
```
3. ISC redirects the user to a login prompt to authenticate to Identity Security Cloud.
@@ -280,12 +280,12 @@ GET https://{tenant}.login.sailpoint.com/oauth/authorize?client_id={client-id}&r
6. The web app submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token?grant_type=authorization_code&client_id={client-id}&code={code}&redirect_uri={redirect-url}
POST https://[tenant].api.identitynow.com/oauth/token?grant_type=authorization_code&client_id={client-id}&code={code}&redirect_uri={redirect-url}
```
:::info
The token endpoint URL is `{tenant}.api.identitynow.com`, and the authorize URL is `{tenant}.login.sailpoint.com`. Please be sure to use the correct URL when you're setting up your webapp to use this flow. You can read more about [finding your tenant OAuth details here](https://developer.sailpoint.com/docs/api/authentication/#find-your-tenants-oauth-details).
The token endpoint URL is `[tenant].api.identitynow.com`, and the authorize URL is `[tenant].login.sailpoint.com`. Please be sure to use the correct URL when you're setting up your webapp to use this flow. You can read more about [finding your tenant OAuth details here](https://developer.sailpoint.com/docs/api/authentication/#find-your-tenants-oauth-details).
:::
@@ -296,7 +296,7 @@ These are the query parameters in the OAuth 2.0 token request for the authorizat
| Key | Description |
| --- | --- |
| `grant_type` | Set this to `authorization_code` for the authorization code grant type. |
| `client_id` | This is the client ID for the API client (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). This can be generated at `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel` |
| `client_id` | This is the client ID for the API client (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). This can be generated at `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel` |
| `code` | This is a code returned by `/oauth/authorize`. |
| `redirect_uri` | This is the application URL to redirect to once the token has been granted. |
@@ -317,7 +317,7 @@ For more information about the OAuth authorization code grant flow, refer [here]
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.
The OAuth 2.0 client you are using must have `REFRESH_TOKEN` as one of its grant types, and you would typically use this type in conjunction with another grant type, like `CLIENT_CREDENTIALS` or `AUTHORIZATION_CODE`:
The OAuth 2.0 client you are using must have `REFRESH_TOKEN` and `AUTHORIZATION_CODE` as its grant types:
```json
{
@@ -337,12 +337,12 @@ The OAuth 2.0 client you are using must have `REFRESH_TOKEN` as one of its grant
This is the overall authorization flow:
1. The client application receives an `access_token` and a `refresh_token` from one of the other OAuth grant flows, like `AUTHORIZATION_CODE`.
1. The client application receives an `access_token` and a `refresh_token` when using the `AUTHORIZATION_CODE` grant flow.
2. The client application detects that the `access_token` is about to expire, based on the `expires_in` attribute contained within the JWT token.
3. The client submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token?grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}
POST https://[tenant].api.identitynow.com/oauth/token?grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}
```
4. ISC validates the token request and submits a response. If the request is successful, the response contains a new `access_token` and `refresh_token`.
@@ -352,8 +352,8 @@ These are the query parameters in the OAuth 2.0 token request for the refresh to
| Key | Description |
| --- | --- |
| `grant_type` | Set to `refresh_token` for the authorization code grant type. |
| `client_id` | This is the client ID for the API client (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). This can be generated at `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`. |
| `client_secret` | This is the client secret for the API client (e.g. `c924417c85b19eda40e171935503d8e9747ca60ddb9b48ba4c6bb5a7145fb6c5`). This can be generated at `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`. |
| `client_id` | This is the client ID for the API client (e.g. `b61429f5-203d-494c-94c3-04f54e17bc5c`). This can be generated at `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`. |
| `client_secret` | This is the client secret for the API client (e.g. `c924417c85b19eda40e171935503d8e9747ca60ddb9b48ba4c6bb5a7145fb6c5`). This can be generated at `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`. |
| `refresh_token` | This is the `refresh_token` that was provided along with the now expired `access_token`. |
Here is an example call OAuth 2.0 Token Request for the Refresh Token grant.
@@ -370,7 +370,7 @@ For more information about the OAuth refresh token grant flow, refer [here](http
### OAuth token response
A successful request using any of the grant flows to `https://{tenant}.api.identitynow.com/oauth/token` will contain a response body like this:
A successful request using any of the grant flows to `https://[tenant].api.identitynow.com/oauth/token` will contain a response body like this:
```json
{
@@ -397,7 +397,7 @@ You can use the JWT `access_token` to authorize REST API calls through the ISC A
```bash
curl -X GET \
'https://{tenant}.api.identitynow.com/v3/account-activities' \
'https://[tenant].api.identitynow.com/v3/account-activities' \
-H 'Authorization: Bearer {access_token}' \
-H 'cache-control: no-cache'
```
@@ -521,13 +521,13 @@ Having issues? Follow these steps:
### 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`
2. Verify that the API calls are going through the API gateway: `https://[tenant].api.identitynow.com`
3. Verify you are calling their version correctly:
- Private APIs: `https://{tenant}.api.identitynow.com/cc/api/{endpoint}`
- V2 APIs: `https://{tenant}.api.identitynow.com/v2/{endpoint}`
- V3 APIs: `https://{tenant}.api.identitynow.com/v3/{endpoint}`
- Beta APIs: `https://{tenant}.api.identitynow.com/beta/{endpoint}`
- Private APIs: `https://[tenant].api.identitynow.com/cc/api/{endpoint}`
- V2 APIs: `https://[tenant].api.identitynow.com/v2/{endpoint}`
- V3 APIs: `https://[tenant].api.identitynow.com/v3/{endpoint}`
- Beta APIs: `https://[tenant].api.identitynow.com/beta/{endpoint}`
4. Verify that the API calls have the correct headers (e.g., `content-type`), query parameters, and body data.
5. If the HTTP response is **401 Unauthorized** , this is an indication either that there is no `Authorization` header or that the `access_token` is invalid. Verify that the API calls are providing the `access_token` in the `Authorization` header correctly (ex. `Authorization: Bearer {access_token}`) and that the `access_token` has not expired.
@@ -559,7 +559,7 @@ or
GET /beta/oauth-clients/
```
You can also view all of the active clients in the UI by going to `https://{tenant}.identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`.
You can also view all of the active clients in the UI by going to `https://[tenant].identitynow.com/ui/admin/#admin:global:security:apimanagementpanel`.
3. Verify that the OAuth 2.0 client grant types match the OAuth 2.0 grant type flow you're trying to use. For example, this client will work with [Authorization Code](#authorization-code-grant-flow) and [Client Credentials](#client-Credentials-grant-flow) grant flows, but not [Refresh Token](#refresh-token-grant-flow) flows:
@@ -583,4 +583,4 @@ You can also view all of the active clients in the UI by going to `https://{tena
### 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`.

View File

@@ -43,13 +43,9 @@ sequenceDiagram
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/accounts/identities.html#setting-user-level-permissions).
:::caution
User levels are typically granted through the UI, [following the procedures from this document](https://documentation.sailpoint.com/saas/help/accounts/identities.html#setting-user-level-permissions). You can also set user levels via API using the [auth user update](https://developer.sailpoint.com/docs/api/v3/patch-auth-user) endpoint.
There is an [API that can set an identity's user level](https://developer.sailpoint.com/discuss/t/assign-identitynow-admin-roles-via-api/1874/4), but it is a V1 API with no guaranteed support. Use it at your own risk!
:::
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.
@@ -100,7 +96,7 @@ When you create a PAT in the UI, you can apply scopes to the token. More informa
You can [create PATs](https://developer.sailpoint.com/docs/api/v3/create-personal-access-token) programmatically with the API. The request body for the endpoint allows the caller to specify a list of scopes to be applied to the PAT. If the `scope` property is omitted from the request body, then `sp:scopes:all` is granted to the credentials. The following example shows how to generate a PAT with the `idn:access-request:manage` and `idn:nelm:manage` scopes.
POST <https://{tenant}.api.identitynow.com/v3/personal-access-tokens>
POST `https://{tenant}.api.identitynow.com/v3/personal-access-tokens`
Request Body

View File

@@ -69,7 +69,7 @@ There is a rate limit of 100 requests per `access_token` per 10 seconds for V3 A
**Headers**:
- **Retry-After**: {seconds to wait before rate limit resets}
- **Retry-After**: [seconds to wait before rate limit resets]
## API Tools

View File

@@ -179,7 +179,7 @@ This rule searches for profiles based on an attribute that profile has.
| 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> |
| 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 |
Example:

View File

@@ -51,7 +51,7 @@ To send API requests in Postman, you must authenticate to the APIs. To authentic
:::caution
Don't specify your baseUrl in your environment variables. When you fork an API collection, the baseUrl is automatically set as <https://{{tenant}}.api.{{domain}}.com>. Setting your baseURl in your environment variables may interfere with this process.
Don't specify your baseUrl in your environment variables. When you fork an API collection, the baseUrl is automatically set as `https://{{tenant}}.api.{{domain}}.com`. Setting your baseURl in your environment variables may interfere with this process.
:::

View File

@@ -18,4 +18,4 @@ There is a rate limit of 100 requests per `access_token` per 10 seconds for V3 A
**Headers**:
- **Retry-After**: {seconds to wait before rate limit resets}
- **Retry-After**: [seconds to wait before rate limit resets]

View File

@@ -5,9 +5,9 @@ pagination_label: Standard Collection Parameters
sidebar_label: Standard Collection Parameters
sidebar_position: 5
sidebar_class_name: standardCollectionParameters
keywords: ['standard collection parameters']
keywords: ['standard collection parameters','filter','pagination','paginate','sort']
description: ISC API pagination, filtering, and sorting.
tags: ['Standard Collection Parameters']
tags: ['Standard Collection Parameters','Filter','Sort','Pagination']
---
Many endpoints in the Identity Security Cloud API support a generic syntax for paginating, filtering and sorting the results. A collection endpoint has the following characteristics:
@@ -50,7 +50,7 @@ The `searchAfter` capability provides the ability to page on sorted field values
Here is an example of a search API call with `searchAfter` paging. The first query will get the first set of results. The default limit for search is 10,000, which is different from other collection endpoints. For this example, the query is set to page 100 records at a time. Paginating search queries also requires the `sort` property to be set to `id`.
**POST** <https://{tenant}.api.identitynow.com/v3/search?limit=100&count=true>
**POST** `https://{tenant}.api.identitynow.com/v3/search?limit=100&count=true`
```json
{
@@ -64,7 +64,7 @@ Here is an example of a search API call with `searchAfter` paging. The first que
This query will return 100 records. To get the next 100 records, find the last record's `id` and use it in the next query's `searchAfter` property.
**POST** <https://{tenant}.api.identitynow.com/v3/search?limit=100&count=true>
**POST** `https://{tenant}.api.identitynow.com/v3/search?limit=100&count=true`
```json
{
@@ -108,11 +108,11 @@ These filter operators apply directly to fields and their values:
| `ca` | True if the collection-valued field contains all the listed values. | groups ca ("Venezia","Firenze") |
| `co` | True if the value of the field contains the specified value as a substring.(Applicable to string-valued fields only.) | name co "Rajesh" |
| `eq` | True if the value of the field indicated by the first operand is equal to the value specified by the second operand. | identitySummary.id eq "2c9180846e85e4b8016eafeba20c1314" |
| `ge` | True if the value of the field indicated by the first operand is greater or equal to the value specified by the second operand. | daysUntilEscalation ge 7 name ge "Genaro" |
| `gt` | True if the value of the field indicated by the first operand is greater than the value specified by the second operand. | daysUntilEscalation gt 7 name gt "Genaro" created gt 2018-12-18T23:05:55Z |
| `ge` | True if the value of the field indicated by the first operand is greater or equal to the value specified by the second operand. | daysUntilEscalation ge 7<br></br><br></br>name ge "Genaro" |
| `gt` | True if the value of the field indicated by the first operand is greater than the value specified by the second operand. | daysUntilEscalation gt 7<br></br><br></br>name gt "Genaro"<br></br><br></br>created gt 2018-12-18T23:05:55Z |
| `in` | True if the field value is in the list of values. | accountActivityItemId in ("2c9180846b0a0583016b299f210c1314","2c9180846b0a0581016b299e82560c1314") |
| `le` | True if the value of the field indicated by the first operand is less or equal to the value specified by the second operand. | daysUntilEscalation le 7 name le "Genaro" |
| `lt` | True if the value of the field indicated by the first operand is less than the value specified by the second operand. | daysUntilEscalation lt 7 name lt "Genaro" created lt 2018-12-18T23:05:55Z |
| `le` | True if the value of the field indicated by the first operand is less or equal to the value specified by the second operand. | daysUntilEscalation le 7<br></br><br></br>name le "Genaro" |
| `lt` | True if the value of the field indicated by the first operand is less than the value specified by the second operand. | daysUntilEscalation lt 7<br></br><br></br>name lt "Genaro"<br></br><br></br>created lt 2018-12-18T23:05:55Z |
| `ne` | True if the value of the field indicated by the first operand is not equal to the value specified by the second operand. | type ne "ROLE" |
| `pr` | True if the field is present, that is, not null. | pr accountRequestInfo |
| `isnull` | True if the field is null. | lastUsed isnull |