API docs by Redocly

Identity Security Cloud V3 API (3.0.0)

URL: https://developer.sailpoint.com/discuss/api-help License: MIT Terms of Service

Use these APIs to interact with the Identity Security Cloud platform to achieve repeatable, automated processes with greater scalability. We encourage you to join the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss to connect with other developers using our APIs.

Access Profiles

Use this API to implement and customize access profile functionality. With this functionality in place, administrators can create access profiles and configure them for use throughout Identity Security Cloud, enabling users to get the access they need quickly and securely.

Access profiles group entitlements, which represent access rights on sources.

For example, an Active Directory source in Identity Security Cloud can have multiple entitlements: the first, 'Employees,' may represent the access all employees have at the organization, and a second, 'Developers,' may represent the access all developers have at the organization.

An administrator can then create a broader set of access in the form of an access profile, 'AD Developers' grouping the 'Employees' entitlement with the 'Developers' entitlement.

When users only need Active Directory employee access, they can request access to the 'Employees' entitlement.

When users need both Active Directory employee and developer access, they can request access to the 'AD Developers' access profile.

Identity Security Cloud uses access profiles in many features, including the following:

  • Provisioning: When you use the Provisioning Service, lifecycle states and roles both grant access to users in the form of access profiles.

  • Certifications: You can approve or revoke access profiles in certification campaigns, just like entitlements.

  • Access Requests: You can assign access profiles to applications, and when a user requests access to the app associated with an access profile and someone approves the request, access is granted to both the application and its associated access profile.

  • Roles: You can group one or more access profiles into a role to quickly assign access items based on an identity's role.

In Identity Security Cloud, administrators can use the Access drop-down menu and select Access Profiles to view, configure, and delete existing access profiles, as well as create new ones. Administrators can enable and disable an access profile, and they can also make the following configurations:

  • Manage Entitlements: Manage the profile's access by adding and removing entitlements.

  • Access Requests: Configure access profiles to be requestable and establish an approval process for any requests that the access profile be granted or revoked. Do not configure an access profile to be requestable without first establishing a secure access request approval process for the access profile.

  • Multiple Account Options: Define the logic Identity Security Cloud uses to provision access to an identity with multiple accounts on the source.

Refer to Managing Access Profiles for more information about access profiles.

List access profiles

Get a list of access profiles.

Note: When you filter for access profiles that have the '+' symbol in their names, the response is blank.

Authorizations:
Personal Access Token
query Parameters
for-subadmin
string
Example: for-subadmin=8c190e6787aa4ed9a90bd9d5344523fb

Filters the returned list according to what is visible to the indicated ROLE_SUBADMIN or SOURCE_SUBADMIN identity. The value of the parameter is either an identity ID or the special value me, which is shorthand for the calling identity's ID.

If you specify an identity that isn't a subadmin, the API returns a 400 Bad Request error.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=name eq "SailPoint Support"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, sw

created: gt, ge, le

modified: gt, lt, ge, le

owner.id: eq, in

requestable: eq

source.id: eq, in

Supported composite operators are and, or

Filtering is not supported for access profiles and entitlements that have the '+' symbol in their names.

sorters
string <comma-separated>
Example: sorters=name,-modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, created, modified

for-segment-ids
string <comma-separated>
Example: for-segment-ids=0b5c9f25-83c6-4762-9073-e38f7bb2ae26,2e8d8180-24bc-4d21-91c6-7affdb473b0d

Filters access profiles to only those assigned to the segment(s) with the specified IDs. If segmentation is currently unavailable, specifying this parameter results in an error.

include-unsegmented
boolean
Default: true

Indicates whether the response list should contain unsegmented access profiles. If for-segment-ids is absent or empty, specifying include-unsegmented as false results in an error.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create access profile

Create an access profile. A user with ROLE_SUBADMIN or SOURCE_SUBADMIN authority must be associated with the access profile's source. The maximum supported length for the description field is 2000 characters. Longer descriptions will be preserved for existing access profiles. However, any new access profiles as well as any updates to existing descriptions are limited to 2000 characters.

Note: To use this endpoint, you need all the listed scopes.

Authorizations:
Personal Access Token
Request Body schema: application/json
name
required
string

Access profile name.

description
string or null

Access profile description.

enabled
boolean
Default: false

Indicates whether the access profile is enabled. If it's enabled, you must include at least one entitlement.

required
object (OwnerReference)

Owner of the object.

required
object (AccessProfileSourceRef)
Array of objects or null (EntitlementRef)

List of entitlements associated with the access profile. If enabled is false, this can be empty. Otherwise, it must contain at least one entitlement.

requestable
boolean
Default: true

Indicates whether the access profile is requestable by access request. Currently, making an access profile non-requestable is only supported for customers enabled with the new Request Center. Otherwise, attempting to create an access profile with a value false in this field results in a 400 error.

object or null (Requestability)
object or null (Revocability)
segments
Array of strings or null

List of segment IDs, if any, that the access profile is assigned to.

object (AttributeDTOList)
object or null (ProvisioningCriteriaLevel1)

Defines matching criteria for an account to be provisioned with a specific access profile.

Array of objects or null (AdditionalOwnerRef)

List of additional owner references beyond the primary owner. Each entry may be an identity (IDENTITY) or a governance group (GOVERNANCE_GROUP).

Responses

Request samples

Content type
application/json
{
  • "name": "Employee-database-read-write",
  • "description": "Collection of entitlements to read/write the employee database",
  • "enabled": true,
  • "owner": {
    },
  • "source": {
    },
  • "entitlements": [
    ],
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "accessModelMetadata": {
    },
  • "provisioningCriteria": {
    },
  • "additionalOwners": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "2c91808a7190d06e01719938fcd20792",
  • "name": "Employee-database-read-write",
  • "description": "Collection of entitlements to read/write the employee database",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "enabled": true,
  • "owner": {
    },
  • "source": {
    },
  • "entitlements": [
    ],
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "accessModelMetadata": {
    },
  • "provisioningCriteria": {
    },
  • "additionalOwners": [
    ]
}

Get an access profile

This API returns an Access Profile by its ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180837ca6693d017ca8d097500149

ID of the Access Profile

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808a7190d06e01719938fcd20792",
  • "name": "Employee-database-read-write",
  • "description": "Collection of entitlements to read/write the employee database",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "enabled": true,
  • "owner": {
    },
  • "source": {
    },
  • "entitlements": [
    ],
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "accessModelMetadata": {
    },
  • "provisioningCriteria": {
    },
  • "additionalOwners": [
    ]
}

Patch a specified access profile

This API updates an existing Access Profile. The following fields are patchable:

name

description

enabled

owner

additionalOwners

requestable

accessRequestConfig

revokeRequestConfig

segments

entitlements

provisioningCriteria

source (must be updated with entitlements belonging to new source in the same API call)

If you need to change the source of the access profile, you can do so only if you update the entitlements in the same API call. The new entitlements can only come from the target source that you want to change to. Look for the example "Replace Source" in the examples dropdown.

A user with SOURCE_SUBADMIN may only use this API to patch Access Profiles which are associated with Sources they are able to administer.

The maximum supported length for the description field is 2000 characters. Longer descriptions will be preserved for existing access profiles, however, any new access profiles as well as any updates to existing descriptions will be limited to 2000 characters.

You can only add or replace entitlements that exist on the source that the access profile is attached to. You can use the list entitlements endpoint with the filters query parameter to get a list of available entitlements on the access profile's source.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the Access Profile to patch

Request Body schema: application/json-patch+json
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
Example

Add one or more entitlements to the end of the list

[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c91808a7190d06e01719938fcd20792",
  • "name": "Employee-database-read-write",
  • "description": "Collection of entitlements to read/write the employee database",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "enabled": true,
  • "owner": {
    },
  • "source": {
    },
  • "entitlements": [
    ],
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "accessModelMetadata": {
    },
  • "provisioningCriteria": {
    },
  • "additionalOwners": [
    ]
}

Delete the specified access profile

This API deletes an existing Access Profile.

The Access Profile must not be in use, for example, Access Profile can not be deleted if they belong to an Application, Life Cycle State or a Role. If it is, a 400 error is returned.

A user with SOURCE_SUBADMIN must be able to administer the Source associated with the Access Profile.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the Access Profile to delete

Responses

Response samples

Content type
application/json

Returned when an access profile cannot be deleted as it's being used

{
  • "detailCode": "400.2.1.0 Object in use by another",
  • "trackingId": "c9c1033c55b84ebc9e93e926dcf8b8b3",
  • "messages": [
    ]
}

Delete access profile(s)

This endpoint initiates a bulk deletion of one or more access profiles. When the request is successful, the endpoint returns the bulk delete's task result ID. To follow the task, you can use Get Task Status by ID, which will return the task result's status and information. This endpoint can only bulk delete up to a limit of 50 access profiles per request. By default, if any of the indicated access profiles are in use, no deletions will be performed and the inUse field of the response indicates the usages that must be removed first. If the request field bestEffortOnly is true, however, usages are reported in the inUse response field but all other indicated access profiles will be deleted. A SOURCE_SUBADMIN user can only use this endpoint to delete access profiles associated with sources they're able to administer.

Authorizations:
Personal Access Token
Request Body schema: application/json
accessProfileIds
Array of strings

List of IDs of Access Profiles to be deleted.

bestEffortOnly
boolean

If true, silently skip over any of the specified Access Profiles if they cannot be deleted because they are in use. If false, no deletions will be attempted if any of the Access Profiles are in use.

Responses

Request samples

Content type
application/json
{
  • "bestEffortOnly": true,
  • "accessProfileIds": [
    ]
}

Response samples

Content type
application/json
{
  • "pending": [ ],
  • "inUse": [
    ]
}

List access profile's entitlements

Use this API to get a list of an access profile's entitlements. A SOURCE_SUBADMIN user must have access to the source associated with the specified access profile.

Note: When you filter for access profiles that have the '+' symbol in their names, the response is blank.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the access profile containing the entitlements.

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=attribute eq "memberOf"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, sw

attribute: eq, sw

value: eq, sw

created: gt, lt, ge, le

modified: gt, lt, ge, le

owner.id: eq, in

source.id: eq, in

Filtering is not supported for access profiles and entitlements that have the '+' symbol in their names.

sorters
string <comma-separated>
Example: sorters=name,-modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, attribute, value, created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Access Request Approvals

Use this API to implement and customize access request approval functionality. With this functionality in place, administrators can delegate qualified users to review users' requests for access or managers' requests to revoke team members' access to applications, entitlements, or roles.
This enables more qualified users to review access requests and the others to spend their time on other tasks.

In Identity Security Cloud, users can request access to applications, entitlements, and roles, and managers can request that team members' access be revoked.
For applications and entitlements, administrators can set access profiles to require approval from the access profile owner, the application owner, the source owner, the requesting user's manager, or a governance group for access to be granted or revoked.
For roles, administrators can also set roles to allow access requests and require approval from the role owner, the requesting user's manager, or a governance group for access to be granted or revoked.
If the administrator designates a governance group as the required approver, any governance group member can approve the requests.

When a user submits an access request, Identity Security Cloud sends the first required approver in the queue an email notification, based on the access request configuration's approval and reminder escalation configuration.

In Approvals in Identity Security Cloud, required approvers can view pending access requests under the Requested tab and approve or deny them, or the approvers can reassign the requests to different reviewers for approval.
If the required approver approves the request and is the only reviewer required, Identity Security Cloud grants or revokes access, based on the request.
If multiple reviewers are required, Identity Security Cloud sends the request to the next reviewer in the queue, based on the access request configuration's approval reminder and escalation configuration.
The required approver can then view any completed access requests under the Reviewed tab.

Refer to Access Requests for more information about access request approvals.

Pending access request approvals list

This endpoint returns a list of pending approvals. See "owner-id" query parameter below for authorization info.

Authorizations:
Personal Access Token
query Parameters
owner-id
string
Example: owner-id=2c91808568c529c60168cca6f90c1313

If present, the value returns only pending approvals for the specified identity.

  • ORG_ADMIN users can call this with any identity ID value.
  • ORG_ADMIN users can also fetch all the approvals in the org, when owner-id is not used.
  • Non-ORG_ADMIN users can only specify me or pass their own identity ID value.
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "2c91808568c529c60168cca6f90c1313"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

requestedFor.id: eq, in

modified: gt, lt, ge, le, eq, in

accessRequestId: eq, in

created: gt, lt, ge, le, eq, in

sorters
string <comma-separated>
Example: sorters=modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Completed access request approvals list

This endpoint returns list of completed approvals. See owner-id query parameter below for authorization info.

Authorizations:
Personal Access Token
query Parameters
owner-id
string
Example: owner-id=2c91808568c529c60168cca6f90c1313

If present, the value returns only completed approvals for the specified identity.

  • ORG_ADMIN users can call this with any identity ID value.
  • ORG_ADMIN users can also fetch all the approvals in the org, when owner-id is not used.
  • Non-ORG_ADMIN users can only specify me or pass their own identity ID value.
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "2c91808568c529c60168cca6f90c1313"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in, ge, gt, le, lt, ne, isnull, sw

requestedFor.id: eq, in, ge, gt, le, lt, ne, isnull, sw

modified: gt, lt, ge, le, eq, in, ne, sw

sorters
string <comma-separated>
Example: sorters=modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Approve access request approval

Use this endpoint to approve an access request approval. Only the owner of the approval and ORG_ADMIN users are allowed to perform this action.

Authorizations:
Personal Access Token
path Parameters
approvalId
required
string
Example: 2c91808b7294bea301729568c68c002e

Approval ID.

Request Body schema: application/json

Reviewer's comment.

comment
string or null

Comment content.

created
string <date-time>

Date and time comment was created.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a comment.",
  • "created": "2017-07-11T18:45:37.098Z"
}

Response samples

Content type
application/json
{ }

Reject access request approval

Use this API to reject an access request approval. Only the owner of the approval and admin users are allowed to perform this action.

Authorizations:
Personal Access Token
path Parameters
approvalId
required
string
Example: 2c91808b7294bea301729568c68c002e

Approval ID.

Request Body schema: application/json

Reviewer's comment.

comment
string or null

Comment content.

created
string <date-time>

Date and time comment was created.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a comment.",
  • "created": "2017-07-11T18:45:37.098Z"
}

Response samples

Content type
application/json
{ }

Forward access request approval

Use this API to forward an access request approval to a new owner. Only the owner of the approval and ORG_ADMIN users are allowed to perform this action. Only the owner of the approval and ORG_ADMIN users are allowed to perform this action.

Authorizations:
Personal Access Token
path Parameters
approvalId
required
string
Example: 2c91808b7294bea301729568c68c002e

Approval ID.

Request Body schema: application/json

Information about the forwarded approval.

newOwnerId
required
string [ 1 .. 255 ] characters

The Id of the new owner

comment
required
string [ 1 .. 255 ] characters

The comment provided by the forwarder

Responses

Request samples

Content type
application/json
{
  • "newOwnerId": "2c91808568c529c60168cca6f90c1314",
  • "comment": "2c91808568c529c60168cca6f90c1313"
}

Response samples

Content type
application/json
{ }

Get access requests approvals number

Use this API to return the number of pending, approved and rejected access requests approvals. See the "owner-id" query parameter for authorization information. info.

Authorizations:
Personal Access Token
query Parameters
owner-id
string
Example: owner-id=2c91808568c529c60168cca6f90c1313

The ID of the owner or approver identity of the approvals. If present, the value returns approval summary for the specified identity.

  • ORG_ADMIN users can call this with any identity ID value.
  • ORG_ADMIN user can also fetch all the approvals in the org, when owner-id is not used.
  • Non ORG_ADMIN users can only specify me or pass their own identity ID value.
from-date
string
Example: from-date=from-date=2020-03-19T19:59:11Z

This is the date and time the results will be shown from. It must be in a valid ISO-8601 format.

Responses

Response samples

Content type
application/json
{
  • "pending": 0,
  • "approved": 0,
  • "rejected": 0
}

Access Requests

Use this API to implement and customize access request functionality. With this functionality in place, users can request access to applications, entitlements, or roles, and managers can request that team members' access be revoked. This allows users to get access to the tools they need quickly and securely, and it allows managers to take away access to those tools.

Identity Security Cloud's Access Request service allows end users to request access that requires approval before it can be granted to users and enables qualified users to review those requests and approve or deny them.

In the Request Center in Identity Security Cloud, users can view available applications, roles, and entitlements and request access to them. If the requested tools requires approval, the requests appear as 'Pending' under the My Requests tab until the required approver approves, rejects, or cancels them.

Users can use My Requests to track and/or cancel the requests.

In My Team on the Identity Security Cloud Home, managers can submit requests to revoke their team members' access. They can use the My Requests tab under Request Center to track and/or cancel the requests.

Refer to Requesting Access for more information about access requests.

Submit access request

Use this API to submit an access request in Identity Security Cloud (ISC), where it follows any ISC approval processes.

:::info The ability to request access using this API is constrained by the Access Request Segments defined in the API token's user context. :::

Access requests are processed asynchronously by ISC. A successful response from this endpoint means that the request has been submitted to ISC and is queued for processing. Because this endpoint is asynchronous, it does not return an error if you submit duplicate access requests in quick succession or submit an access request for access that is already in progress, approved, or rejected.

It is best practice to check for any existing access requests that reference the same access items before submitting a new access request. This can be accomplished by using the List Access Request Status or the Pending Access Request Approvals APIs. You can also use the Search API to check the existing access items an identity has before submitting an access request to ensure that you aren't requesting access that is already granted. If you use this API to request access that an identity already has, without changing the account details or end date information from the existing assignment, the API will cancel the request as a duplicate.

There are two types of access request:

GRANT_ACCESS

  • Can be requested for multiple identities in a single request.
  • Supports self request and request on behalf of other users. Refer to the Get Access Request Configuration endpoint for request configuration options.
  • Allows any authenticated token (except API) to call this endpoint to request to grant access to themselves. Depending on the configuration, a user can request access for others.
  • Roles, access profiles and entitlements can be requested.
  • You can specify a startDate to set or alter a sunrise date-time on an assignment. The startDate must be a future date-time, in the UTC timezone. Additionally, if the user already has the access assigned with a sunrise date and its yet to be provisioned, you can also submit a request without a startDate to request immediate provisioning after approval.
  • If a startDate is specified, then the requested role, access profile, or entitlement will be provisioned on that date and time.
  • You can specify a removeDate to set or alter a sunset date-time on an assignment. The removeDate must be a future date-time, in the UTC timezone. Additionally, if the user already has the access assigned with a sunset date, you can also submit a request without a removeDate to request removal of the sunset date and time.
  • If a removeDate is specified, then the requested role, access profile, or entitlement will be removed on that date and time.
  • Now supports an alternate field 'requestedForWithRequestedItems' for users to specify account selections while requesting items where they have more than one account on the source.

:::caution

If any entitlements are being requested, then the maximum number of entitlements that can be requested is 25, and the maximum number of identities that can be requested for is 10. If you exceed these limits, the request will fail with a 400 error. If you are not requesting any entitlements, then there are no limits.

:::

REVOKE_ACCESS

  • Can only be requested for a single identity at a time.
  • You cannot use an access request to revoke access from an identity if that access has been granted by role membership or by birthright provisioning.
  • Does not support self request. Only manager can request to revoke access for their directly managed employees.
  • If a removeDate is specified, then the requested role, access profile, or entitlement will be removed on that date and time.
  • Roles, access profiles, and entitlements can be requested for revocation.
  • Revoke requests for entitlements are limited to 1 entitlement per access request currently.
  • You cannot specify a 'startDate' in a REVOKE_ACCESS request, as startDate is only applicable for GRANT_ACCESS requests to indicate when the access should be provisioned, and it does not make sense in the context of revoking access.
  • You can specify a removeDate to add or alter a sunset date and time on an assignment. The removeDate must be a future date-time, in the UTC timezone. If the user already has the access assigned with a sunset date and time, the removeDate must be a date-time earlier than the existing sunset date and time.
  • Allows a manager to request to revoke access for direct employees. A user with ORG_ADMIN authority can also request to revoke access from anyone.
  • Now supports REVOKE_ACCESS requests for identities with multiple accounts on a single source, with the help of 'assignmentId' and 'nativeIdentity' fields. These fields should be used within the 'requestedItems' section for the revoke requests.
  • Usage of 'requestedForWithRequestedItems' field is not supported for revoke requests.
Authorizations:
Personal Access Token
Request Body schema: application/json
requestedFor
required
Array of strings

A list of Identity IDs for whom the Access is requested. If it's a Revoke request, there can only be one Identity ID.

requestType
string or null (AccessRequestType)
Enum: "GRANT_ACCESS" "REVOKE_ACCESS" "MODIFY_ACCESS" null

Access request type. Defaults to GRANT_ACCESS. REVOKE_ACCESS type can only have a single Identity ID in the requestedFor field. MODIFY_ACCESS type is used for updating access expiration dates or other access modifications.

required
Array of objects (Access Request Item) non-empty
object

Arbitrary key-value pairs. They will never be processed by the IdentityNow system but will be returned on associated APIs such as /account-activities.

Array of objects or null (RequestedForDtoRef)

Additional submit data structure with requestedFor containing requestedItems allowing distinction for each request item and Identity.

  • Can only be used when 'requestedFor' and 'requestedItems' are not separately provided
  • Adds ability to specify which account the user wants the access on, in case they have multiple accounts on a source
  • Allows the ability to request items with different start dates
  • Allows the ability to request items with different remove dates
  • Also allows different combinations of request items and identities in the same request
  • Only for use in GRANT_ACCESS type requests

Responses

Request samples

Content type
application/json
{
  • "requestedFor": "2c918084660f45d6016617daa9210584",
  • "requestType": "GRANT_ACCESS",
  • "requestedItems": [
    ],
  • "clientMetadata": {
    },
  • "requestedForWithRequestedItems": [
    ]
}

Response samples

Content type
application/json
{
  • "newRequests": [
    ],
  • "existingRequests": [
    ]
}

Cancel access request

This API endpoint cancels a pending access request. An access request can be cancelled only if it has not passed the approval step. In addition to users with ORG_ADMIN, any user who originally submitted the access request may cancel it.

Authorizations:
Personal Access Token
Request Body schema: application/json
accountActivityId
required
string

This refers to the identityRequestId. To successfully cancel an access request, you must provide the identityRequestId.

comment
required
string

Reason for cancelling the pending access request.

Responses

Request samples

Content type
application/json
{
  • "accountActivityId": "2c91808568c529c60168cca6f90c1313",
  • "comment": "I requested this role by mistake."
}

Response samples

Content type
application/json
{ }

Get access request configuration Deprecated

This endpoint returns the current access-request configuration.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "approvalsMustBeExternal": true,
  • "autoApprovalEnabled": true,
  • "reauthorizationEnabled": true,
  • "requestOnBehalfOfConfig": {
    },
  • "approvalReminderAndEscalationConfig": {
    },
  • "entitlementRequestConfig": {
    }
}

Update access request configuration Deprecated

This endpoint replaces the current access-request configuration.

Authorizations:
Personal Access Token
Request Body schema: application/json
approvalsMustBeExternal
boolean
Default: false

If this is true, approvals must be processed by an external system. Also, if this is true, it blocks Request Center access requests and returns an error for any user who isn't an org admin.

autoApprovalEnabled
boolean
Default: false

If this is true and the requester and reviewer are the same, the request is automatically approved.

reauthorizationEnabled
boolean
Default: false

If this is true, reauthorization will be enforced for appropriately configured access items. Enablement of this feature is currently in a limited state.

object (Request On Behalf Of Config)
object (Approval Reminder And Escalation Config)
object (Entitlement Request Config)

Responses

Request samples

Content type
application/json
{
  • "approvalsMustBeExternal": true,
  • "autoApprovalEnabled": true,
  • "reauthorizationEnabled": true,
  • "requestOnBehalfOfConfig": {
    },
  • "approvalReminderAndEscalationConfig": {
    },
  • "entitlementRequestConfig": {
    }
}

Response samples

Content type
application/json
{
  • "approvalsMustBeExternal": true,
  • "autoApprovalEnabled": true,
  • "reauthorizationEnabled": true,
  • "requestOnBehalfOfConfig": {
    },
  • "approvalReminderAndEscalationConfig": {
    },
  • "entitlementRequestConfig": {
    }
}

Access request status

Use this API to return a list of access request statuses based on the specified query parameters. If an access request was made for access that an identity already has, the API ignores the access request. These ignored requests do not display in the list of access request statuses. Any user with any user level can get the status of their own access requests. A user with ORG_ADMIN is required to call this API to get a list of statuses for other users.

Authorizations:
Personal Access Token
query Parameters
requested-for
string
Example: requested-for=2c9180877b2b6ea4017b2c545f971429

Filter the results by the identity the requests were made for. me indicates the current user. Mutually exclusive with regarding-identity.

requested-by
string
Example: requested-by=2c9180877b2b6ea4017b2c545f971429

Filter the results by the identity who made the requests. me indicates the current user. Mutually exclusive with regarding-identity.

regarding-identity
string
Example: regarding-identity=2c9180877b2b6ea4017b2c545f971429

Filter the results by the specified identity who is either the requester or target of the requests. me indicates the current user. Mutually exclusive with requested-for and requested-by.

assigned-to
string
Example: assigned-to=2c9180877b2b6ea4017b2c545f971429

Filter the results by the specified identity who is the owner of the Identity Request Work Item. me indicates the current user.

count
boolean
Default: false

If this is true, the X-Total-Count response header populates with the number of results that would be returned if limit and offset were ignored.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=100

Max number of results to return.

offset
integer <int32> >= 0
Example: offset=10

Offset into the full result set. Usually specified with limit to paginate through the results. Defaults to 0 if not specified.

filters
string
Example: filters=accountActivityItemId eq "2c918086771c86df0177401efcdf54c0"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

accessRequestId: eq, ge, gt, le, lt, ne, in, sw

accountActivityItemId: eq, in, ge, gt, le, ne, sw

created: eq, ge, gt, le, lt, ne

sorters
string <comma-separated>
Example: sorters=created

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: created, modified, accountActivityItemId, name

request-state
string
Example: request-state=request-state=EXECUTING

Filter the results by the state of the request. The only valid value is EXECUTING.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Account Activities

Use this API to implement account activity tracking functionality. With this functionality in place, users can track source account activity in Identity Security Cloud, which greatly improves traceability in the system.

An account activity refers to a log of each action performed on a source account. This is useful for auditing the changes performed on an account throughout its life. In Identity Security Cloud's Search, users can search for account activities and select the activity's row to get an overview of the activity's account action and view its progress, its involved sources, and its most basic metadata, such as the identity requesting the option and the recipient.

Account activity includes most actions Identity Security Cloud completes on source accounts. Users can search in Identity Security Cloud for the following account action types:

  • Access Request: These include any access requests the source account is involved in.

  • Account Attribute Updates: These include updates to a single attribute on an account on a source.

  • Account State Update: These include locking or unlocking actions on an account on a source.

  • Certification: These include actions removing an entitlement from an account on a source as a result of the entitlement's revocation during a certification.

  • Cloud Automated Lifecyclestate: These include automated lifecycle state changes that result in a source account's correlated identity being assigned to a different lifecycle state. Identity Security Cloud replaces the Lifecyclestate variable with the name of the lifecycle state it has moved the account's identity to.

  • Identity Attribute Update: These include updates to a source account's correlated identity attributes as the result of a provisioning action. When you update an identity attribute that also updates an identity's lifecycle state, the cloud automated Lifecyclestate event also displays. Account Activity does not include attribute updates that occur as a result of aggregation.

  • Identity Refresh: These include correlated identity refreshes that occur for an account on a source whenever the account's correlated identity profile gets a new role or updates. These also include refreshes that occur whenever Identity Security Cloud assigns an application to the account's correlated identity based on the application's being assigned to All Users From Source or Specific Users From Source.

  • Lifecycle State Refresh: These include the actions that took place when a lifecycle state changed. This event only occurs after a cloud automated Lifecyclestate change or a lifecycle state change.

  • Lifecycle State Change: These include the account activities that result from an identity's manual assignment to a null lifecycle state.

  • Password Change: These include password changes on sources.

Refer to Account Activity for more information about account activities.

List account activities

This gets a collection of account activities that satisfy the given query parameters.

Authorizations:
Personal Access Token
query Parameters
requested-for
string
Example: requested-for=2c91808568c529c60168cca6f90c1313

The identity that the activity was requested for. me indicates the current user. Mutually exclusive with regarding-identity.

requested-by
string
Example: requested-by=2c91808568c529c60168cca6f90c1313

The identity that requested the activity. me indicates the current user. Mutually exclusive with regarding-identity.

regarding-identity
string
Example: regarding-identity=2c91808568c529c60168cca6f90c1313

The specified identity will be either the requester or target of the account activity. me indicates the current user. Mutually exclusive with requested-for and requested-by.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=type eq "Identity Refresh"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

type: eq, in, ge, le, lt, ne, isnull, sw

created: gt, lt, ge, le, eq, in, ne, isnull, sw

modified: gt, lt, ge, le, eq, in, ne, isnull, sw

sorters
string <comma-separated>
Example: sorters=created

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: type, created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an account activity

This gets a single account activity by its id.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account activity id

Responses

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "name": "2c9180835d2e5168015d32f890ca1581",
  • "created": "2017-07-11T18:45:37.098Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "completed": "2018-10-19T13:49:37.385Z",
  • "completionStatus": "SUCCESS",
  • "type": "appRequest",
  • "requesterIdentitySummary": {
    },
  • "targetIdentitySummary": {
    },
  • "errors": [
    ],
  • "warnings": [
    ],
  • "items": [
    ],
  • "executionStatus": "COMPLETED",
  • "clientMetadata": {
    }
}

Account Usages

Use this API to implement account usage insight functionality. With this functionality in place, administrators can gather information and insights about how their tenants' source accounts are being used. This allows organizations to get the information they need to start optimizing and securing source account usage.

Returns account usage insights

This API returns a summary of account usage insights for past 12 months.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
accountId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

ID of IDN account

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

sorters
string <comma-separated>
Example: sorters=-date

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accounts

Use this API to implement and customize account functionality. With this functionality in place, administrators can manage users' access across sources in Identity Security Cloud.

In Identity Security Cloud, an account refers to a user's account on a supported source. This typically includes a unique identifier for the user, a unique password, a set of permissions associated with the source and a set of attributes. Identity Security Cloud loads accounts through the creation of sources in Identity Security Cloud.

Administrators can correlate users' identities with the users' accounts on the different sources they use. This allows Identity Security Cloud to govern the access of identities and all their correlated accounts securely and cohesively.

To view the accounts on a source and their correlated identities, administrators can use the Connections drop-down menu, select Sources, select the relevant source, and select its Account tab.

To view and edit source account statuses for an identity in Identity Security Cloud, administrators can use the Identities drop-down menu, select Identity List, select the relevant identity, and select its Accounts tab. Administrators can toggle an account's Actions to aggregate the account, enable/disable it, unlock it, or remove it from the identity.

Accounts can have the following statuses:

  • Enabled: The account is enabled. The user can access it.

  • Disabled: The account is disabled, and the user cannot access it, but the identity is not disabled in Identity Security Cloud. This can occur when an administrator disables the account or when the user's lifecycle state changes.

  • Locked: The account is locked. This may occur when someone has entered an incorrect password for the account too many times.

  • Pending: The account is currently updating. This status typically lasts seconds.

Administrators can select the source account to view its attributes, entitlements, and the last time the account's password was changed.

Refer to Managing User Accounts for more information about accounts.

Accounts list

List accounts.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

detailLevel
string
Enum: "SLIM" "FULL"
Example: detailLevel=FULL

This value determines whether the API provides SLIM or increased level of detail (FULL) for each account in the returned list. FULL is the default behavior.

filters
string
Example: filters=identityId eq "2c9180858082150f0180893dbaf44201"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in, sw

identityId: eq, in, sw

name: eq, in, sw

nativeIdentity: eq, in, sw

hasEntitlements: eq

sourceId: eq, in, sw

uncorrelated: eq

entitlements: eq

origin: eq, in

manuallyCorrelated: eq

identity.name: eq, in, sw

identity.correlated: eq

identity.identityState: eq, in

source.displayableName: eq, in

source.authoritative: eq

source.connectionType: eq, in

recommendation.method: eq, in, isnull

created: eq, ge, gt, le, lt

modified: eq, ge, gt, le, lt

sorters
string <comma-separated>
Example: sorters=id,name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: id, name, created, modified, sourceId, identityId, nativeIdentity, uuid, manuallyCorrelated, entitlements, origin, identity.name, identity.identityState, identity.correlated, source.displayableName, source.authoritative, source.connectionType

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create account

Submit an account creation task - the API then returns the task ID.

You must include the sourceId where the account will be created in the attributes object.

This endpoint creates an account on the source record in your ISC tenant. This is useful for Flat File (DelimitedFile) type sources because it allows you to aggregate new accounts without needing to import a new CSV file every time.

However, if you use this endpoint to create an account for a Direct Connection type source, you must ensure that the account also exists on the target source. The endpoint doesn't actually provision the account on the target source, which means that if the account doesn't also exist on the target source, an aggregation between the source and your tenant will remove it from your tenant.

By providing the account ID of an existing account in the request body, this API will function as a PATCH operation and update the account.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
required
object

The schema attribute values for the account

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Account details

Use this API to return the details for a single account by its ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Account ID.

Responses

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "sourceId": "2c9180835d2e5168015d32f890ca1581",
  • "sourceName": "Employees",
  • "identityId": "2c9180835d2e5168015d32f890ca1581",
  • "cloudLifecycleState": "active",
  • "identityState": "ACTIVE",
  • "connectionType": "direct",
  • "isMachine": true,
  • "recommendation": {
    },
  • "attributes": {
    },
  • "authoritative": false,
  • "description": null,
  • "disabled": false,
  • "locked": false,
  • "nativeIdentity": "552775",
  • "systemAccount": false,
  • "uncorrelated": false,
  • "uuid": "{b0dce506-d6d4-44d2-8a32-d9a5b21fb175}",
  • "manuallyCorrelated": false,
  • "hasEntitlements": true,
  • "identity": {
    },
  • "sourceOwner": {
    },
  • "features": "ENABLE",
  • "origin": "AGGREGATED",
  • "ownerIdentity": {
    }
}

Update account

Use this API to update account details.

This API supports updating an account's correlation by modifying the identityId and manuallyCorrelated fields. To reassign an account from one identity to another, replace the current identityId with a new value. If the account you're assigning was provisioned by Identity Security Cloud (ISC), it's possible for ISC to create a new account for the previous identity as soon as the account is moved. If the account you're assigning is authoritative, this causes the previous identity to become uncorrelated and can even result in its deletion. All accounts that are reassigned will be set to manuallyCorrelated: true unless you specify otherwise.

Note: The attributes field can only be modified for flat file accounts.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Account ID.

Request Body schema: application/json-patch+json

A list of account update operations according to the JSON Patch standard.

Array
object

Responses

Request samples

Content type
application/json-patch+json
Example

Remove account from Identity

[
  • {
    }
]

Response samples

Content type
application/json
{ }

Update account

Use this API to update an account with a PUT request.

This endpoint submits an account update task and returns the task ID.

Note: You can only use this PUT endpoint to update accounts from flat file sources.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Account ID.

Request Body schema: application/json
required
object

The schema attribute values for the account

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Delete account

Use this API to delete an account. This endpoint submits an account delete task and returns the task ID. This endpoint only deletes the account from IdentityNow, not the source itself, which can result in the account's returning with the next aggregation between the source and IdentityNow. To avoid this scenario, it is recommended that you disable accounts rather than delete them. This will also allow you to reenable the accounts in the future.

NOTE: You can only delete accounts from sources of the "DelimitedFile" type.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Account ID.

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Account entitlements

This API returns entitlements of the account.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account id

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reload account

This API asynchronously reloads the account directly from the connector and performs a one-time aggregation process.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account id

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Enable account

This API submits a task to enable account and returns the task ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account id

Request Body schema: application/json
externalVerificationId
string

If set, an external process validates that the user wants to proceed with this request.

forceProvisioning
boolean

If set, provisioning updates the account attribute at the source. This option is used when the account is not synced to ensure the attribute is updated. Providing 'true' for an unlocked account will add and process 'Unlock' operation by the workflow.

Responses

Request samples

Content type
application/json
{
  • "externalVerificationId": "3f9180835d2e5168015d32f890ca1581",
  • "forceProvisioning": false
}

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Disable account

This API submits a task to disable the account and returns the task ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account id

Request Body schema: application/json
externalVerificationId
string

If set, an external process validates that the user wants to proceed with this request.

forceProvisioning
boolean

If set, provisioning updates the account attribute at the source. This option is used when the account is not synced to ensure the attribute is updated. Providing 'true' for an unlocked account will add and process 'Unlock' operation by the workflow.

Responses

Request samples

Content type
application/json
{
  • "externalVerificationId": "3f9180835d2e5168015d32f890ca1581",
  • "forceProvisioning": false
}

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Unlock account

This API submits a task to unlock an account and returns the task ID.
To use this endpoint to unlock an account that has the forceProvisioning option set to true, the idn:accounts-provisioning:manage scope is required.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The account ID.

Request Body schema: application/json
externalVerificationId
string

If set, an external process validates that the user wants to proceed with this request.

unlockIDNAccount
boolean

If set, the IDN account is unlocked after the workflow completes.

forceProvisioning
boolean

If set, provisioning updates the account attribute at the source. This option is used when the account is not synced to ensure the attribute is updated.

Responses

Request samples

Content type
application/json
{
  • "externalVerificationId": "3f9180835d2e5168015d32f890ca1581",
  • "unlockIDNAccount": false,
  • "forceProvisioning": false
}

Response samples

Content type
application/json
{
  • "id": "2c91808474683da6017468693c260195"
}

Application Discovery

Use this API to implement application discovery functionality. With this functionality in place, you can discover applications within your Okta connector and receive connector recommendations by manually uploading application names.

Download csv template for discovery

Download an example CSV file with two columns application_name and description. The CSV file contains a single row with the values 'Example Application' and 'Example Description'.

The downloaded template is specifically designed for use with the /manual-discover-applications endpoint.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
text/csv
application_name,description
Example Application,Example Description

Upload csv to discover applications

Uploading a CSV file with application data for manual correlation to specific ISC connectors. If a suitable ISC connector is unavailable, the system will recommend generic connectors instead.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: multipart/form-data
file
required
string <binary>

The CSV file to upload containing application_name and description columns. Each row represents an application to be discovered.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get discovered applications for tenant

Get a list of applications that have been identified within the environment. This includes details such as application names, discovery dates, potential correlated saas_vendors and related suggested connectors.

Authorizations:
Personal Access Token
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

detail
string
Enum: "SLIM" "FULL"
Example: detail=FULL

Determines whether slim, or increased level of detail is provided for each discovered application in the returned list. SLIM is the default behavior.

filter
string
Example: filter=name eq "Okta" and description co "Okta" and discoverySource in ("csv", "Okta Saas")

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

name: eq, sw, co

description: eq, sw, co

createdAtStart: eq, le, ge

createdAtEnd: eq, le, ge

discoveredAtStart: eq, le, ge

discoveredAtEnd: eq, le, ge

discoverySource: eq, in

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, description, discoveredAt, discoverySource

Responses

Response samples

Content type
application/json
Example

List of discovered applications

[
  • {
    },
  • {
    },
  • {
    }
]

Auth Users

Use this API to implement user authentication system functionality. With this functionality in place, users can get a user's authentication system details, including their capabilities, and modify those capabilities. The user's capabilities refer to their access to different systems, or authorization, within the tenant, like access to certifications (CERT_ADMIN) or reports (REPORT_ADMIN). These capabilities also determine a user's access to the different APIs. This API provides users with a way to determine a user's access and make quick and easy changes to that access.

Auth user details

Return the specified user's authentication system details.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Identity ID

Responses

Response samples

Content type
application/json
{
  • "tenant": "test-tenant",
  • "id": "2c91808458ae7a4f0158b1bbf8af0628",
  • "uid": "will.smith",
  • "profile": "2c91808458ae7a4f0158b1bbf8af0756",
  • "identificationNumber": "19-5588452",
  • "email": "william.smith@example.com",
  • "phone": "5555555555",
  • "workPhone": "5555555555",
  • "personalEmail": "william.smith@example.com",
  • "firstname": "Will",
  • "lastname": "Smith",
  • "displayName": "Will Smith",
  • "alias": "will.smith",
  • "lastPasswordChangeDate": "2021-03-08T22:37:33.901Z",
  • "lastLoginTimestamp": 1656327185832,
  • "currentLoginTimestamp": 1656327185832,
  • "lastUnlockTimestamp": "2021-03-08T22:37:33.901Z",
  • "capabilities": [
    ]
}

Auth user update

Use a PATCH request to update an existing user in the authentication system. Use this endpoint to modify these fields:

  • capabilities

A '400.1.1 Illegal update attempt' detail code indicates that you attempted to PATCH a field that is not allowed.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Identity ID

Request Body schema: application/json-patch+json

A list of auth user update operations according to the JSON Patch standard.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "tenant": "test-tenant",
  • "id": "2c91808458ae7a4f0158b1bbf8af0628",
  • "uid": "will.smith",
  • "profile": "2c91808458ae7a4f0158b1bbf8af0756",
  • "identificationNumber": "19-5588452",
  • "email": "william.smith@example.com",
  • "phone": "5555555555",
  • "workPhone": "5555555555",
  • "personalEmail": "william.smith@example.com",
  • "firstname": "Will",
  • "lastname": "Smith",
  • "displayName": "Will Smith",
  • "alias": "will.smith",
  • "lastPasswordChangeDate": "2021-03-08T22:37:33.901Z",
  • "lastLoginTimestamp": 1656327185832,
  • "currentLoginTimestamp": 1656327185832,
  • "lastUnlockTimestamp": "2021-03-08T22:37:33.901Z",
  • "capabilities": [
    ]
}

Branding

Use this API to implement and customize branding functionality. With this functionality in place, administrators can get and manage existing branding items, and they can also create new branding items and configure them for use throughout Identity Security Cloud. The Branding APIs provide administrators with a way to customize branding items. This customization includes details like their colors, logos, and other information. Refer to Certifications for more information about certifications.

List of branding items

This API endpoint returns a list of branding items.

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a branding item

This API endpoint creates a branding item.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: multipart/form-data
name
required
string

name of branding item

productName
required
string or null

product name

actionButtonColor
string

hex value of color for action button

activeLinkColor
string

hex value of color for link

navigationColor
string

hex value of color for navigation bar

emailFromAddress
string

email from address

loginInformationalMessage
string

login information message

fileStandard
string <binary>

png file with logo

Responses

Response samples

Content type
application/json
{
  • "name": "default",
  • "productName": "product name",
  • "actionButtonColor": "0074D9",
  • "activeLinkColor": "011E69",
  • "navigationColor": "011E69",
  • "emailFromAddress": "no-reply@sailpoint.com",
  • "standardLogoURL": "",
  • "loginInformationalMessage": ""
}

Get a branding item

This API endpoint retrieves information for an existing branding item by name.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
name
required
string
Example: default

The name of the branding item to be retrieved

Responses

Response samples

Content type
application/json
{
  • "name": "default",
  • "productName": "product name",
  • "actionButtonColor": "0074D9",
  • "activeLinkColor": "011E69",
  • "navigationColor": "011E69",
  • "emailFromAddress": "no-reply@sailpoint.com",
  • "standardLogoURL": "",
  • "loginInformationalMessage": ""
}

Update a branding item

This API endpoint updates information for an existing branding item.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
name
required
string
Example: default

The name of the branding item to be retrieved

Request Body schema: multipart/form-data
name
required
string

name of branding item

productName
required
string or null

product name

actionButtonColor
string

hex value of color for action button

activeLinkColor
string

hex value of color for link

navigationColor
string

hex value of color for navigation bar

emailFromAddress
string

email from address

loginInformationalMessage
string

login information message

fileStandard
string <binary>

png file with logo

Responses

Response samples

Content type
application/json
{
  • "name": "default",
  • "productName": "product name",
  • "actionButtonColor": "0074D9",
  • "activeLinkColor": "011E69",
  • "navigationColor": "011E69",
  • "emailFromAddress": "no-reply@sailpoint.com",
  • "standardLogoURL": "",
  • "loginInformationalMessage": ""
}

Delete a branding item

This API endpoint delete information for an existing branding item by name.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
name
required
string
Example: default

The name of the branding item to be deleted

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Certification Campaign Filters

Use this API to implement the certification campaign filter functionality. These filters can be used to create a certification campaign that includes a subset of your entitlements or users to certify.

For example, if for a certification campaign an organization wants to certify only specific users or entitlements, then those can be included/excluded on the basis of campaign filters.

For more information about creating a campaign filter, refer to Creating a Campaign Filter

You can create campaign filters using any of the following criteria types:

  • Access Profile : This criteria type includes or excludes access profiles from a campaign.

  • Account Attribute : This criteria type includes or excludes certification items that match a specified value in an account attribute.

  • Entitlement : This criteria type includes or excludes entitlements from a campaign.

  • Identity : This criteria type includes or excludes specific identities from your campaign.

  • Identity Attribute : This criteria type includes or excludes identities based on whether they have an identity attribute that matches criteria you've chosen.

  • Role : This criteria type includes or excludes roles, as opposed to identities.

  • Source : This criteria type includes or excludes entitlements from a source you select.

For more information about these criteria types, refer to Types of Campaign Filters

Once the campaign filter is created, it can be linked while creating the campaign. The generated campaign will have the items to review as per the campaign filter.

For example, An inclusion campaign filter is created with a source of Source 1, an operation of Equals, and an entitlement of Entitlement 1. When this filter is selected, only users who have Entitlement 1 are included in the campaign, and only Entitlement 1 is shown in the certification.

Create campaign filter

Use this API to create a campaign filter based on filter details and criteria.

Authorizations:
Personal Access Token
Request Body schema: application/json
id
required
string

The unique ID of the campaign filter

name
required
string

Campaign filter name.

description
string

Campaign filter description.

owner
required
string or null

Owner of the filter. This field automatically populates at creation time with the current user.

mode
required
string
Enum: "INCLUSION" "EXCLUSION"

Mode/type of filter, either the INCLUSION or EXCLUSION type. The INCLUSION type includes the data in generated campaigns as per specified in the criteria, whereas the EXCLUSION type excludes the data in generated campaigns as per specified in criteria.

Array of objects

List of criteria.

isSystemFilter
required
boolean
Default: false

If true, the filter is created by the system. If false, the filter is created by a user.

Responses

Request samples

Content type
application/json
{
  • "id": "5ec18cef39020d6fd7a60ad3970aba61",
  • "name": "Identity Attribute Campaign Filter",
  • "description": "Campaign filter to certify data based on an identity attribute's specified property.",
  • "owner": "SailPoint Support",
  • "mode": "INCLUSION",
  • "criteriaList": [
    ],
  • "isSystemFilter": false
}

Response samples

Content type
application/json
{
  • "id": "5ec18cef39020d6fd7a60ad3970aba61",
  • "name": "Identity Attribute Campaign Filter",
  • "description": "Campaign filter to certify data based on an identity attribute's specified property.",
  • "owner": "SailPoint Support",
  • "mode": "INCLUSION",
  • "criteriaList": [
    ],
  • "isSystemFilter": false
}

List campaign filters

Use this API to list all campaign filters. You can reduce scope with standard V3 query parameters.

Authorizations:
Personal Access Token
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

start
integer <int32> >= 0
Default: 0

Start/Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

includeSystemFilters
boolean
Default: true
Example: includeSystemFilters=true

If this is true, the API includes system filters in the count and results. Otherwise it excludes them. If no value is provided, the default is true.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 2
}

Get campaign filter by id

Retrieves information for an existing campaign filter using the filter's ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: e9f9a1397b842fd5a65842087040d3ac

The ID of the campaign filter to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "id": "5ec18cef39020d6fd7a60ad3970aba61",
  • "name": "Identity Attribute Campaign Filter",
  • "description": "Campaign filter to certify data based on an identity attribute's specified property.",
  • "owner": "SailPoint Support",
  • "mode": "INCLUSION",
  • "criteriaList": [
    ],
  • "isSystemFilter": false
}

Updates a campaign filter

Updates an existing campaign filter using the filter's ID.

Authorizations:
Personal Access Token
path Parameters
filterId
required
string
Example: e9f9a1397b842fd5a65842087040d3ac

The ID of the campaign filter being modified.

Request Body schema: application/json

A campaign filter details with updated field values.

id
required
string

The unique ID of the campaign filter

name
required
string

Campaign filter name.

description
string

Campaign filter description.

owner
required
string or null

Owner of the filter. This field automatically populates at creation time with the current user.

mode
required
string
Enum: "INCLUSION" "EXCLUSION"

Mode/type of filter, either the INCLUSION or EXCLUSION type. The INCLUSION type includes the data in generated campaigns as per specified in the criteria, whereas the EXCLUSION type excludes the data in generated campaigns as per specified in criteria.

Array of objects

List of criteria.

isSystemFilter
required
boolean
Default: false

If true, the filter is created by the system. If false, the filter is created by a user.

Responses

Request samples

Content type
application/json
{
  • "id": "5ec18cef39020d6fd7a60ad3970aba61",
  • "name": "Identity Attribute Campaign Filter",
  • "description": "Campaign filter to certify data based on an identity attribute's specified property.",
  • "owner": "SailPoint Support",
  • "mode": "INCLUSION",
  • "criteriaList": [
    ],
  • "isSystemFilter": false
}

Response samples

Content type
application/json
{
  • "id": "5ec18cef39020d6fd7a60ad3970aba61",
  • "name": "Identity Attribute Campaign Filter",
  • "description": "Campaign filter to certify data based on an identity attribute's specified property.",
  • "owner": "SailPoint Support",
  • "mode": "INCLUSION",
  • "criteriaList": [
    ],
  • "isSystemFilter": false
}

Deletes campaign filters

Deletes campaign filters whose Ids are specified in the provided list of campaign filter Ids. Authorized callers must be an ORG_ADMIN or a CERT_ADMIN.

Authorizations:
Personal Access Token
Request Body schema: application/json

A json list of IDs of campaign filters to delete.

Array
string

Responses

Request samples

Content type
application/json
[
  • "0fbe863c063c4c88a35fd7f17e8a3df5",
  • "2efb374d392c4d88a34sv7b11e8a4eq6"
]

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Certification Campaigns

Use this API to implement certification campaign functionality. With this functionality in place, administrators can create, customize, and manage certification campaigns for their organizations' use. Certification campaigns provide Identity Security Cloud users with an interactive review process they can use to identify and verify access to systems. Campaigns help organizations reduce risk of inappropriate access and satisfy audit requirements.

A certification refers to Identity Security Cloud's mechanism for reviewing a user's access to entitlements (sets of permissions) and approving or removing that access. These certifications serve as a way of showing that a user's access has been reviewed and approved. Multiple certifications by different reviewers are often required to approve a user's access. A set of multiple certifications is called a certification campaign.

For example, an organization may use a Manager Certification campaign as a way of showing that a user's access has been reviewed and approved by multiple managers. Once this campaign has been completed, Identity Security Cloud would provision all the access the user needs, nothing more.

Identity Security Cloud provides two simple campaign types users can create without using search queries, Manager and Source Owner campaigns:

You can create these types of campaigns without using any search queries in Identity Security Cloud:

  • ManagerCampaign: Identity Security Cloud provides this campaign type as a way to ensure that an identity's access is certified by their managers. You only need to provide a name and description to create one.

  • Source Owner Campaign: Identity Security Cloud provides this campaign type as a way to ensure that an identity's access to a source is certified by its source owners. You only need to provide a name and description to create one. You can specify the sources whose owners you want involved or just run it across all sources.

For more information about these campaign types, refer to Starting a Manager or Source Owner Campaign.

One useful way to create certification campaigns in Identity Security Cloud is to use a specific search and then run a campaign on the results returned by that search. This allows you to be much more specific about whom you are certifying in your campaigns and what access you are certifying in your campaigns. For example, you can search for all identities who are managed by "Amanda.Ross" and also have the access to the "Accounting" role and then run a certification campaign based on that search to ensure that the returned identities are appropriately certified.

You can use Identity Security Cloud search queries to create these types of campaigns:

  • Identities: Use this campaign type to review and revoke access items for specific identities. You can either build a search query and create a campaign certifying all identities returned by that query, or you can search for individual identities and add those identities to the certification campaign.

  • Access Items: Use this campaign type to review and revoke a set of roles, access profiles, or entitlements from the identities that have them. You can either build a search query and create a campaign certifying all access items returned by that query, or you can search for individual access items and add those items to the certification campaign.

  • Role Composition: Use this campaign type to review a role's composition, including its title, description, and membership criteria. You can either build a search query and create a campaign certifying all roles returned by that query, or you can search for individual roles and add those roles to the certification campaign.

  • Uncorrelated Accounts: Use this campaign type to certify source accounts that aren't linked to an authoritative identity in Identity Security Cloud. You can use this campaign type to view all the uncorrelated accounts for a source and certify them.

For more information about search-based campaigns, refer to Starting a Campaign from Search.

Once you have generated your campaign, it becomes available for preview. An administrator can review the campaign and make changes, or if it's ready and accurate, activate it.

Once the campaign is active, organization administrators or certification administrators can designate other Identity Security Cloud users as certification reviewers. Those reviewers can view any of the certifications they either need to review (active) or have already reviewed (completed).

When a certification campaign is in progress, certification reviewers see the listed active certifications whose involved identities they can review. Reviewers can then make decisions to grant or revoke access, as well as reassign the certification to another reviewer. If the reviewer chooses this option, they must provide a reason for reassignment in the form of a comment.

Once a reviewer has made decisions on all the certification's involved access items, he or she must "Sign Off" to complete the review process. Doing so converts the certification into read-only status, preventing any further changes to the review decisions and deleting the work item (task) from the reviewer's list of work items.

Once all the reviewers have signed off, the certification campaign either completes or, if any reviewers decided to revoke access for any of the involved identities, it moves into a remediation phase. In the remediation phase, identities' entitlements are altered to remove any entitlements marked for revocation. In this situation, the certification campaign completes once all the remediation requests are completed.

The end of a certification campaign is determined by its deadline, its completion status, or by an administrator's decision.

For more information about certifications and certification campaigns, refer to Certifications.

List campaigns

Use this API to get a list of campaigns. This API can provide increased level of detail for each campaign for the correct provided query.

Authorizations:
Personal Access Token
query Parameters
detail
string
Enum: "SLIM" "FULL"
Example: detail=FULL

Determines whether slim, or increased level of detail is provided for each campaign in the returned list. Slim is the default behavior.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=name eq "Manager Campaign"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, sw

status: eq, in

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, created

Responses

Response samples

Content type
application/json
Example

List of Slim Campaigns that would result from not specifying detail or specifying SLIM

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create a campaign

Use this API to create a certification campaign with the information provided in the request body.

Authorizations:
Personal Access Token
Request Body schema: application/json
name
required
string

The campaign name. If this object is part of a template, special formatting applies; see the /campaign-templates/{id}/generate endpoint documentation for details.

description
required
string or null

The campaign description. If this object is part of a template, special formatting applies; see the /campaign-templates/{id}/generate endpoint documentation for details.

deadline
string <date-time>

The campaign's completion deadline. This date must be in the future in order to activate the campaign. If you try to activate a campaign with a deadline of today or in the past, you will receive a 400 error response.

type
required
string
Enum: "MANAGER" "SOURCE_OWNER" "SEARCH" "ROLE_COMPOSITION" "MACHINE_ACCOUNT"

The type of campaign. Could be extended in the future.

emailNotificationEnabled
boolean
Default: false

Enables email notification for this campaign

autoRevokeAllowed
boolean
Default: false

Allows auto revoke for this campaign

recommendationsEnabled
boolean
Default: false

Enables IAI for this campaign. Accepts true even if the IAI product feature is off. If IAI is turned off then campaigns generated from this template will indicate false. The real value will then be returned if IAI is ever enabled for the org in the future.

correlatedStatus
string
Enum: "CORRELATED" "UNCORRELATED"

The correlatedStatus of the campaign. Only SOURCE_OWNER campaigns can be Uncorrelated. An Uncorrelated certification campaign only includes Uncorrelated identities (An identity is uncorrelated if it has no accounts on an authoritative source).

object

Determines which items will be included in this campaign. The default campaign filter is used if this field is left blank.

sunsetCommentsRequired
boolean
Default: true

Determines if comments on sunset date changes are required.

object

Must be set only if the campaign type is SOURCE_OWNER.

object

Must be set only if the campaign type is SEARCH.

object

Optional configuration options for role composition campaigns.

object

Must be set only if the campaign type is MACHINE_ACCOUNT.

mandatoryCommentRequirement
string
Enum: "ALL_DECISIONS" "REVOKE_ONLY_DECISIONS" "NO_DECISIONS"

Determines whether comments are required for decisions during certification reviews. You can require comments for all decisions, revoke-only decisions, or no decisions. By default, comments are not required for decisions.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Manager Review",
  • "description": "A review of everyone's access by their manager.",
  • "deadline": "2020-12-25T06:00:00.468Z",
  • "type": "MANAGER",
  • "emailNotificationEnabled": false,
  • "autoRevokeAllowed": false,
  • "recommendationsEnabled": false,
  • "filter": {
    },
  • "mandatoryCommentRequirement": "NO_DECISIONS"
}

Response samples

Content type
application/json
Example
{
  • "id": "5594f43b76804a6980ece5fdccf74be7",
  • "name": "Manager Review",
  • "description": "A review of everyone's access by their manager.",
  • "deadline": "2020-12-25T06:00:00.468Z",
  • "type": "MANAGER",
  • "status": "PENDING",
  • "emailNotificationEnabled": false,
  • "autoRevokeAllowed": false,
  • "recommendationsEnabled": false,
  • "created": "2022-08-02T20:21:18.421Z",
  • "modified": null,
  • "filter": {
    },
  • "sunsetCommentsRequired": true,
  • "sourceOwnerCampaignInfo": null,
  • "searchCampaignInfo": null,
  • "roleCompositionCampaignInfo": null,
  • "machineAccountCampaignInfo": null,
  • "alerts": null,
  • "totalCertifications": 0,
  • "completedCertifications": 0,
  • "sourcesWithOrphanEntitlements": null,
  • "mandatoryCommentRequirement": "NO_DECISIONS"
}

Get campaign

Use this API to get information for an existing certification campaign by the campaign's ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808571bcfcf80171c23e4b4221fc

ID of the campaign to be retrieved.

query Parameters
detail
string
Enum: "SLIM" "FULL"
Example: detail=FULL

Determines whether slim, or increased level of detail is provided for each campaign in the returned list. Slim is the default behavior.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "2c918086719eec070171a7e3355a360a",
  • "name": "Manager Review",
  • "description": "A review of everyone's access by their manager.",
  • "deadline": "2020-12-25T06:00:00.123Z",
  • "type": "MANAGER",
  • "status": "ACTIVE",
  • "emailNotificationEnabled": false,
  • "autoRevokeAllowed": false,
  • "recommendationsEnabled": false
}

Update a campaign

Use this API to update individual fields on a certification campaign, using the JSON Patch standard.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808571bcfcf80171c23e4b4221fc

ID of the campaign template being modified.

Request Body schema: application/json-patch+json

A list of campaign update operations according to the JSON Patch standard. The fields that can be patched differ based on the status of the campaign.

When the campaign is in the STAGED status, you can patch these fields:

  • name
  • description
  • recommendationsEnabled
  • deadline
  • emailNotificationEnabled
  • autoRevokeAllowed

When the campaign is in the ACTIVE status, you can patch these fields:

  • deadline
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "id": "2c918086719eec070171a7e3355a360a",
  • "name": "Manager Review",
  • "description": "A review of everyone's access by their manager.",
  • "deadline": "2020-12-25T06:00:00.123Z",
  • "type": "MANAGER",
  • "status": "ACTIVE",
  • "emailNotificationEnabled": false,
  • "autoRevokeAllowed": false,
  • "recommendationsEnabled": false
}

Reassign certifications

This API reassigns the specified certifications from one identity to another.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The certification campaign ID

Request Body schema: application/json
certificationIds
Array of strings [ 1 .. 250 ] items

List of certification IDs to reassign

object
reason
string

Comment to explain why the certification was reassigned

Responses

Request samples

Content type
application/json
{
  • "certificationIds": [
    ],
  • "reassignTo": {
    },
  • "reason": "reassigned for some reason"
}

Response samples

Content type
application/json
{
  • "id": "2c918086719eec070171a7e3355a360a",
  • "type": "ADMIN_REASSIGN",
  • "targetType": "CAMPAIGN",
  • "targetId": "2c918086719eec070171a7e3355a834c",
  • "status": "QUEUED",
  • "errors": [ ],
  • "created": "2020-09-24T18:10:47.693Z"
}

Activate a campaign

Use this API to submit a job to activate the certified campaign with the specified ID. The campaign must be staged.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Campaign ID.

Request Body schema: application/json

Optional. If no timezone is specified, the standard UTC timezone is used (i.e. UTC+00:00). Although this can take any timezone, the intended value is the caller's timezone. The activation time calculated from the given timezone may cause the campaign deadline time to be modified, but it will remain within the original date. The timezone must be in a valid ISO 8601 format.

timeZone
string
Default: "Z"

The timezone must be in a valid ISO 8601 format. Timezones in ISO 8601 are represented as UTC (represented as 'Z') or as an offset from UTC. The offset format can be +/-hh:mm, +/-hhmm, or +/-hh.

Responses

Request samples

Content type
application/json
{
  • "timeZone": "-05:00"
}

Response samples

Content type
application/json
{ }

Complete a campaign

:::caution

This endpoint will run successfully for any campaigns that are past due.

This endpoint will return a content error if the campaign is not past due.

:::

Use this API to complete a certification campaign. This functionality is provided to admins so that they can complete a certification even if all items have not been completed.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Campaign ID.

Request Body schema: application/json

Optional. Default behavior is for the campaign to auto-approve upon completion, unless autoCompleteAction=REVOKE

autoCompleteAction
string
Default: "APPROVE"
Enum: "APPROVE" "REVOKE"

Determines whether to auto-approve(APPROVE) or auto-revoke(REVOKE) upon campaign completion.

Responses

Request samples

Content type
application/json
{
  • "autoCompleteAction": "REVOKE"
}

Response samples

Content type
application/json
{ }

Delete campaigns

Use this API to delete certification campaigns whose IDs are specified in the provided list of campaign IDs.

Authorizations:
Personal Access Token
Request Body schema: application/json

IDs of the campaigns to delete.

ids
Array of strings

The ids of the campaigns to delete

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Run campaign remediation scan

Use this API to run a remediation scan task for a certification campaign.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808571bcfcf80171c23e4b4221fc

ID of the campaign the remediation scan is being run for.

Responses

Response samples

Content type
application/json
{ }

Get campaign reports

Use this API to fetch all reports for a certification campaign by campaign ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808571bcfcf80171c23e4b4221fc

ID of the campaign whose reports are being fetched.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Run campaign report

Use this API to run a report for a certification campaign.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808571bcfcf80171c23e4b4221fc

ID of the campaign the report is being run for.

type
required
string (ReportType)
Enum: "CAMPAIGN_COMPOSITION_REPORT" "CAMPAIGN_REMEDIATION_STATUS_REPORT" "CAMPAIGN_STATUS_REPORT" "CERTIFICATION_SIGNOFF_REPORT"
Example: CAMPAIGN_COMPOSITION_REPORT

Type of the report to run.

Responses

Response samples

Content type
application/json
{ }

Get campaign reports configuration

Use this API to fetch the configuration for certification campaign reports. The configuration includes only one element - identity attributes defined as custom report columns.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "identityAttributeColumns": [
    ]
}

Set campaign reports configuration

Use this API to overwrite the configuration for campaign reports.

Authorizations:
Personal Access Token
Request Body schema: application/json

Campaign report configuration.

identityAttributeColumns
Array of strings or null

list of identity attribute columns

Responses

Request samples

Content type
application/json
{
  • "identityAttributeColumns": [
    ]
}

Response samples

Content type
application/json
{
  • "identityAttributeColumns": [
    ]
}

Create a campaign template

Use this API to create a certification campaign template based on campaign.

Authorizations:
Personal Access Token
Request Body schema: application/json
id
string

Id of the campaign template

name
required
string

This template's name. Has no bearing on generated campaigns' names.

description
required
string

This template's description. Has no bearing on generated campaigns' descriptions.

deadlineDuration
string

The time period during which the campaign should be completed, formatted as an ISO-8601 Duration. When this template generates a campaign, the campaign's deadline will be the current date plus this duration. For example, if generation occurred on 2020-01-01 and this field was "P2W" (two weeks), the resulting campaign's deadline would be 2020-01-15 (the current date plus 14 days).

required
object (Campaign)

Responses

Request samples

Content type
application/json
Example

This creates a template that can be used to generate manager campaigns. The campaigns will have a due date that is two weeks after their creation date, and will be named "{current date} Manager Review" (e.g. "2020-03-16 Manager Review").

{
  • "name": "Manager Review",
  • "description": "A review of everyone's access by their manager.",
  • "deadlineDuration": "P2W",
  • "campaign": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "e7dbec99d49349c8951bd84f58a05120",
  • "name": "Manager Review",
  • "created": "2022-08-02T19:16:42.632Z",
  • "modified": null,
  • "description": "A review of everyone's access by their manager.",
  • "deadlineDuration": "P14D",
  • "ownerRef": {
    },
  • "scheduled": false,
  • "campaign": {
    }
}

List campaign templates

Use this API to get a list of all campaign templates. Scope can be reduced through standard V3 query params.

The API returns all campaign templates matching the query parameters.

Authorizations:
Personal Access Token
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, created, modified

filters
string <comma-separated>
Example: filters=name eq "manager template"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

name: eq, ge, gt, in, le, lt, ne, sw

id: eq, ge, gt, in, le, lt, ne, sw

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Update a campaign template

Use this API to update individual fields on a certification campaign template, using the JSON Patch standard.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180835d191a86015d28455b4a2329

ID of the campaign template being modified.

Request Body schema: application/json-patch+json

A list of campaign update operations according to the JSON Patch standard.

The following fields are patchable:

  • name
  • description
  • deadlineDuration
  • campaign (all fields that are allowed during create)
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "id": "e7dbec99d49349c8951bd84f58a05120",
  • "name": "Manager Review",
  • "created": "2022-08-02T19:16:42.632Z",
  • "modified": null,
  • "description": "A review of everyone's access by their manager.",
  • "deadlineDuration": "P14D",
  • "ownerRef": {
    },
  • "scheduled": false,
  • "campaign": {
    }
}

Get a campaign template

Use this API to fetch a certification campaign template by ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180835d191a86015d28455b4a2329

Requested campaign template's ID.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "e7dbec99d49349c8951bd84f58a05120",
  • "name": "Manager Review",
  • "created": "2022-08-02T19:16:42.632Z",
  • "modified": null,
  • "description": "A review of everyone's access by their manager.",
  • "deadlineDuration": "P14D",
  • "ownerRef": {
    },
  • "scheduled": false,
  • "campaign": {
    }
}

Delete a campaign template

Use this API to delete a certification campaign template by ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180835d191a86015d28455b4a2329

ID of the campaign template being deleted.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get campaign template schedule

Use this API to get the schedule for a certification campaign template. The API returns a 404 if there is no schedule set.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 04bedce387bd47b2ae1f86eb0bb36dee

ID of the campaign template whose schedule is being fetched.

Responses

Response samples

Content type
application/json
{
  • "type": "WEEKLY",
  • "months": {
    },
  • "days": {
    },
  • "hours": {
    },
  • "expiration": "2022-09-19 13:55:26",
  • "timeZoneId": "CST"
}

Set campaign template schedule

Use this API to set the schedule for a certification campaign template. If a schedule already exists, the API overwrites it with the new one.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 04bedce387bd47b2ae1f86eb0bb36dee

ID of the campaign template being scheduled.

Request Body schema: application/json
type
required
string
Enum: "WEEKLY" "MONTHLY" "ANNUALLY" "CALENDAR"

Determines the overall schedule cadence. In general, all time period fields smaller than the chosen type can be configured. For example, a DAILY schedule can have 'hours' set, but not 'days'; a WEEKLY schedule can have both 'hours' and 'days' set.

object or null

Specifies which months of a schedule are active. Only valid for ANNUALLY schedule types. Examples:

On February and March:

  • type LIST
  • values "2", "3"

Every 3 months, starting in January (quarterly):

  • type LIST
  • values "1"
  • interval 3

Every two months between July and December:

  • type RANGE
  • values "7", "12"
  • interval 2
object

Specifies which day(s) a schedule is active for. This is required for all schedule types. The "values" field holds different data depending on the type of schedule:

  • WEEKLY: days of the week (1-7)
  • MONTHLY: days of the month (1-31, L, L-1...)
  • ANNUALLY: if the "months" field is also set: days of the month (1-31, L, L-1...); otherwise: ISO-8601 dates without year ("--12-31")
  • CALENDAR: ISO-8601 dates ("2020-12-31")

Note that CALENDAR only supports the LIST type, and ANNUALLY does not support the RANGE type when provided with ISO-8601 dates without year.

Examples:

On Sundays:

  • type LIST
  • values "1"

The second to last day of the month:

  • type LIST
  • values "L-1"

From the 20th to the last day of the month:

  • type RANGE
  • values "20", "L"

Every March 2nd:

  • type LIST
  • values "--03-02"

On March 2nd, 2021:

  • type: LIST
  • values "2021-03-02"
required
object

Specifies which hour(s) a schedule is active for. Examples:

Every three hours starting from 8AM, inclusive:

  • type LIST
  • values "8"
  • interval 3

During business hours:

  • type RANGE
  • values "9", "5"

At 5AM, noon, and 5PM:

  • type LIST
  • values "5", "12", "17"
expiration
string or null <date-time>

Specifies the time after which this schedule will no longer occur.

timeZoneId
string

The time zone to use when running the schedule. For instance, if the schedule is scheduled to run at 1AM, and this field is set to "CST", the schedule will run at 1AM CST.

Responses

Request samples

Content type
application/json
Example

Runs on the 15th and last day of the month, at 5PM.

{
  • "type": "MONTHLY",
  • "hours": {
    },
  • "days": {
    }
}

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Delete campaign template schedule

Use this API to delete the schedule for a certification campaign template. The API returns a 404 if there is no schedule set.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 04bedce387bd47b2ae1f86eb0bb36dee

ID of the campaign template whose schedule is being deleted.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Generate a campaign from template

Use this API to generate a new certification campaign from a campaign template.

The campaign object contained in the template has special formatting applied to its name and description fields that determine the generated campaign's name/description. Placeholders in those fields are formatted with the current date and time upon generation.

Placeholders consist of a percent sign followed by a letter indicating what should be inserted. For example, "%Y" inserts the current year, and a campaign template named "Campaign for %y" generates a campaign called "Campaign for 2020" (assuming the year at generation time is 2020).

Valid placeholders are the date/time conversion suffix characters supported by java.util.Formatter.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180835d191a86015d28455b4a2329

ID of the campaign template to use for generation.

Responses

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "name": "Campaign Name",
  • "type": "CAMPAIGN",
  • "campaignType": "MANAGER",
  • "description": "A description of the campaign",
  • "correlatedStatus": "CORRELATED",
  • "mandatoryCommentRequirement": "NO_DECISIONS"
}

Certification Summaries

Use this API to implement certification summary functionality. With this functionality in place, administrators and designated certification reviewers can review summaries of identity certification campaigns and draw conclusions about the campaigns' scope, security, and effectiveness. Implementing certification summary functionality improves organizations' ability to review their certifications and helps them satisfy audit and regulatory requirements by enabling them to trace access changes and the decisions made in their review processes.

A certification refers to Identity Security Cloud's mechanism for reviewing a user's access to entitlements (sets of permissions) and approving or removing that access. These certifications serve as a way of showing that a user's access has been reviewed and approved. Multiple certifications by different reviewers are often required to approve a user's access. A set of multiple certifications is called a certification campaign.

For example, an organization may use a Manager Certification as a way of showing that a user's access has been reviewed and approved by their manager, or if the certification is part of a campaign, that the user's access has been reviewed and approved by multiple managers. Once this certification has been completed, Identity Security Cloud would provision all the access the user needs, nothing more.

Certification summaries provide information about identity certification campaigns such as the identities involved, the number of decisions made, and the access changed. For example, an administrator or designated certification reviewer can examine the Manager Certification campaign to get an overview of how many entitlement decisions are made in that campaign as opposed to role decisions, which identities would be affected by changes to the campaign, and how those identities' access would be affected.

Summary of certification decisions

This API returns a summary of the decisions made on an identity campaign certification. The decisions are summarized by type. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The certification ID

query Parameters
filters
string
Example: filters=identitySummary.id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

identitySummary.id: eq, in

Responses

Response samples

Content type
application/json
{
  • "entitlementDecisionsMade": 3,
  • "accessProfileDecisionsMade": 5,
  • "roleDecisionsMade": 2,
  • "accountDecisionsMade": 4,
  • "entitlementDecisionsTotal": 6,
  • "accessProfileDecisionsTotal": 10,
  • "roleDecisionsTotal": 4,
  • "accountDecisionsTotal": 8,
  • "entitlementsApproved": 2,
  • "entitlementsRevoked": 1,
  • "accessProfilesApproved": 3,
  • "accessProfilesRevoked": 2,
  • "rolesApproved": 2,
  • "rolesRevoked": 0,
  • "accountsApproved": 1,
  • "accountsRevoked": 3
}

Identity summaries for campaign certification

This API returns a list of the identity summaries for a specific identity campaign certification. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

completed: eq, ne

name: eq, sw

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Access summaries

This API returns a list of access summaries for the specified identity campaign certification and type. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

type
required
string
Enum: "ROLE" "ACCESS_PROFILE" "ENTITLEMENT"
Example: ACCESS_PROFILE

The type of access review item to retrieve summaries for

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=access.id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

completed: eq, ne

access.id: eq, in

access.name: eq, sw

entitlement.sourceName: eq, sw

accessProfile.sourceName: eq, sw

sorters
string <comma-separated>
Example: sorters=access.name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: access.name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Summary for identity

This API returns the summary for an identity on a specified identity campaign certification. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

identitySummaryId
required
string
Example: 2c91808772a504f50172a9540e501ba8

The identity summary ID

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808772a504f50172a9540e501ba7",
  • "name": "Alison Ferguso",
  • "identityId": "2c9180857182306001719937377a33de",
  • "completed": true
}

Certifications

Use this API to implement certification functionality. With this functionality in place, administrators and designated certification reviewers can review users' access certifications and decide whether to approve access, revoke it, or reassign the review to another reviewer. Implementing certifications improves organizations' data security by reducing inappropriate access through a distributed review process and helping them satisfy audit and regulatory requirements.

A certification refers to Identity Security Cloud's mechanism for reviewing a user's access to entitlements (sets of permissions) and approving or removing that access. These serve as a way of showing that a user's access has been reviewed and approved. Multiple certifications by different reviewers are often required to approve a user's access. A set of multiple certifications is called a certification campaign.

For example, an organization may use a Manager Certification as a way of showing that a user's access has been reviewed and approved by their manager, or if the certification is part of a campaign, that the user's access has been reviewed and approved by multiple managers. Once this certification has been completed, Identity Security Cloud would provision all the access the user needs, nothing more.

Organization administrators or certification administrators can designate other Identity Security Cloud users as certification reviewers. Those reviewers can select the 'Certifications' tab to view any of the certifications they either need to review or have already reviewed under the 'Active' and 'Completed' tabs, respectively.

When a certification campaign is in progress, certification reviewers will see certifications listed under 'Active,' where they can review the involved identities. Under the 'Decision' column on the right, next to each access item, reviewers can select the checkmark to approve access, select the 'X' to revoke access, or they can toggle the 'More Options' menu to reassign the certification to another reviewer and provide a reason for reassignment in the form of a comment.

Once a reviewer has made decisions on all the certification's involved access items, he or she must select 'Sign Off' to complete the review process. Doing so converts the certification into read-only status, preventing any further changes to the review decisions and deleting the work item (task) from the reviewer's list of work items.

Once all the reviewers have signed off, the certification campaign either completes or, if any reviewers decided to revoke access for any of the involved identities, it moves into a remediation phase. In the remediation phase, identities' entitlements are altered to remove any entitlements marked for revocation. In this situation, the certification campaign completes once all the remediation requests are completed.

List identity campaign certifications

Use this API to get a list of identity campaign certifications for the specified query parameters. Any authenticated token can call this API, but only certifications you are authorized to review will be returned.

Authorizations:
Personal Access Token
query Parameters
reviewer-identity
string
Example: reviewer-identity=me

Reviewer's identity. me indicates the current user.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

campaign.id: eq, in

phase: eq

completed: eq

sorters
string <comma-separated>
Example: sorters=name,due

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, due, signed

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Identity certification by id

This API returns a single identity campaign certification by its ID. Reviewers for this certification can also call this API. This API does not support requests for certifications assigned to Governance Groups.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The certification id

Responses

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "name": "Source Owner Access Review for Employees [source]",
  • "campaign": {
    },
  • "completed": true,
  • "identitiesCompleted": 5,
  • "identitiesTotal": 10,
  • "created": "2018-06-25T20:22:28.104Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "decisionsMade": 20,
  • "decisionsTotal": 40,
  • "due": "2018-10-19T13:49:37.385Z",
  • "signed": "2018-10-19T13:49:37.385Z",
  • "reviewer": {
    },
  • "reassignment": {
    },
  • "hasErrors": false,
  • "errorMessage": "The certification has an error",
  • "phase": "ACTIVE"
}

List of access review items

This API returns a list of access review items for an identity campaign certification. Reviewers for this certification can also call this API. This API does not support requests for certifications assigned to Governance Groups.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

type: eq

access.type: eq

completed: eq, ne

identitySummary.id: eq, in

identitySummary.name: eq, sw

access.id: eq, in

access.name: eq, sw

entitlement.sourceName: eq, sw

accessProfile.sourceName: eq, sw

sorters
string <comma-separated>
Example: sorters=access.name,-accessProfile.sourceName

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: identitySummary.name, access.name, access.type, entitlement.sourceName, accessProfile.sourceName

entitlements
string
Example: entitlements=identityEntitlement

Filter results to view access review items that pertain to any of the specified comma-separated entitlement IDs.

An error will occur if this param is used with access-profiles or roles as only one of these query params can be used at a time.

access-profiles
string
Example: access-profiles=accessProfile1

Filter results to view access review items that pertain to any of the specified comma-separated access-profle IDs.

An error will occur if this param is used with entitlements or roles as only one of these query params can be used at a time.

roles
string
Example: roles=userRole

Filter results to view access review items that pertain to any of the specified comma-separated role IDs.

An error will occur if this param is used with entitlements or access-profiles as only one of these query params can be used at a time.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Decide on a certification item

The API makes a decision to approve or revoke one or more identity campaign certification items. Reviewers for this certification can also call this API. This API does not support requests for certifications assigned to Governance Groups.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The ID of the identity campaign certification on which to make decisions

Request Body schema: application/json

A non-empty array of decisions to be made.

Array ([ 1 .. 250 ] items)
id
required
string

The id of the review decision

decision
required
string (CertificationDecision)
Enum: "APPROVE" "REVOKE"

The decision to approve or revoke the review item

proposedEndDate
string <date-time>

The date at which a user's access should be taken away. Should only be set for REVOKE decisions.

bulk
required
boolean

Indicates whether decision should be marked as part of a larger bulk decision

object (Review Recommendation)
comments
string

Comments recorded when the decision was made

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "name": "Source Owner Access Review for Employees [source]",
  • "campaign": {
    },
  • "completed": true,
  • "identitiesCompleted": 5,
  • "identitiesTotal": 10,
  • "created": "2018-06-25T20:22:28.104Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "decisionsMade": 20,
  • "decisionsTotal": 40,
  • "due": "2018-10-19T13:49:37.385Z",
  • "signed": "2018-10-19T13:49:37.385Z",
  • "reviewer": {
    },
  • "reassignment": {
    },
  • "hasErrors": false,
  • "errorMessage": "The certification has an error",
  • "phase": "ACTIVE"
}

Reassign identities or items

This API reassigns up to 50 identities or items in an identity campaign certification to another reviewer. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. Reviewers for this certification can also call this API. This API does not support requests for certifications assigned to Governance Groups.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

Request Body schema: application/json
required
Array of objects (Reassign Reference)
reassignTo
required
string

The ID of the identity to which the certification is reassigned

reason
required
string

The reason comment for why the reassign was made

Responses

Request samples

Content type
application/json
{
  • "reassign": [
    ],
  • "reassignTo": "ef38f94347e94562b5bb8424a56397d8",
  • "reason": "reassigned for some reason"
}

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "name": "Source Owner Access Review for Employees [source]",
  • "campaign": {
    },
  • "completed": true,
  • "identitiesCompleted": 5,
  • "identitiesTotal": 10,
  • "created": "2018-06-25T20:22:28.104Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "decisionsMade": 20,
  • "decisionsTotal": 40,
  • "due": "2018-10-19T13:49:37.385Z",
  • "signed": "2018-10-19T13:49:37.385Z",
  • "reviewer": {
    },
  • "reassignment": {
    },
  • "hasErrors": false,
  • "errorMessage": "The certification has an error",
  • "phase": "ACTIVE"
}

Finalize identity certification decisions

This API finalizes all decisions made on an identity campaign certification and initiates any remediations required. Reviewers for this certification can also call this API. This API does not support requests for certifications assigned to Governance Groups.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

Responses

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "name": "Source Owner Access Review for Employees [source]",
  • "campaign": {
    },
  • "completed": true,
  • "identitiesCompleted": 5,
  • "identitiesTotal": 10,
  • "created": "2018-06-25T20:22:28.104Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "decisionsMade": 20,
  • "decisionsTotal": 40,
  • "due": "2018-10-19T13:49:37.385Z",
  • "signed": "2018-10-19T13:49:37.385Z",
  • "reviewer": {
    },
  • "reassignment": {
    },
  • "hasErrors": false,
  • "errorMessage": "The certification has an error",
  • "phase": "ACTIVE"
}

Permissions for entitlement certification item

This API returns the permissions associated with an entitlement certification item based on the certification item's ID. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
certificationId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The certification ID

itemId
required
string
Example: 2c91808671bcbab40171bd945d961227

The certification item ID

query Parameters
filters
string
Example: filters=target eq "SYS.OBJAUTH2"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

target: eq, sw

rights: ca

Supported composite operators: and, or

All field values (second filter operands) are case-insensitive for this API.

Only a single and or or composite filter operator may be used. It must also be used between a target filter and a rights filter, not between 2 filters for the same field.

For example, the following is valid: ?filters=rights+ca+(%22CREATE%22)+and+target+eq+%22SYS.OBJAUTH2%22

The following is invalid: 1?filters=rights+ca+(%22CREATE%22)+and+rights+ca+(%SELECT%22)1

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List of reviewers for certification

This API returns a list of reviewers for the certification. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The certification ID

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=name eq "Bob"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, sw

email: eq, sw

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, email

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reassign certifications asynchronously

This API initiates a task to reassign up to 500 identities or items in an identity campaign certification to another reviewer. The certification-tasks API can be used to get an updated status on the task and determine when the reassignment is complete.

Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The identity campaign certification ID

Request Body schema: application/json
required
Array of objects (Reassign Reference)
reassignTo
required
string

The ID of the identity to which the certification is reassigned

reason
required
string

The reason comment for why the reassign was made

Responses

Request samples

Content type
application/json
{
  • "reassign": [
    ],
  • "reassignTo": "ef38f94347e94562b5bb8424a56397d8",
  • "reason": "reassigned for some reason"
}

Response samples

Content type
application/json
{
  • "id": "2c918086719eec070171a7e3355a360a",
  • "type": "ADMIN_REASSIGN",
  • "targetType": "CAMPAIGN",
  • "targetId": "2c918086719eec070171a7e3355a834c",
  • "status": "QUEUED",
  • "errors": [
    ],
  • "reassignmentTrailDTOs": {
    },
  • "created": "2020-09-24T18:10:47.693Z"
}

Certification task by id

This API returns the certification task for the specified ID. Reviewers for the specified certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 63b32151-26c0-42f4-9299-8898dc1c9daa

The task ID

Responses

Response samples

Content type
application/json
{
  • "id": "2c918086719eec070171a7e3355a360a",
  • "type": "ADMIN_REASSIGN",
  • "targetType": "CAMPAIGN",
  • "targetId": "2c918086719eec070171a7e3355a834c",
  • "status": "QUEUED",
  • "errors": [
    ],
  • "reassignmentTrailDTOs": {
    },
  • "created": "2020-09-24T18:10:47.693Z"
}

List of pending certification tasks

This API returns a list of pending (QUEUED or IN_PROGRESS) certification tasks. Any authenticated token can call this API, but only certification tasks you are authorized to review will be returned.

Authorizations:
Personal Access Token
query Parameters
reviewer-identity
string
Example: reviewer-identity=Ada.1de82e55078344

The ID of reviewer identity. me indicates the current user.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=type eq "ADMIN_REASSIGN"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

targetId: eq, in

type: eq, in

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Configuration Hub

Upload configurations and manage object mappings between tenants.

Configuration files can be managed and deployed using Configuration Hub by uploading a JSON file which contains configuration data.

The function of object mapping allows objects with varying names and IDs to be compared. While objects are compared, a user can replace a value in the source tenant with a new value. Object mapping also helps in locating referenced objects to the source object during the drafting process.

Refer to Uploading a Configuration File for more information about uploading Configuration Files

Refer to Mapping Objects for more information about object mappings.

Gets list of object mappings

This gets a list of existing object mappings between current org and source org. Source org should be "default" when getting object mappings that are not associated to any particular org. The request will need the following security scope:

  • sp:config-object-mapping:read
Authorizations:
Personal Access Token
path Parameters
sourceOrg
required
string
Example: source-org

The name of the source org.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Creates an object mapping

This creates an object mapping between current org and source org. Source org should be "default" when creating an object mapping that is not to be associated to any particular org. The request will need the following security scope:

  • sp:config-object-mapping:manage
Authorizations:
Personal Access Token
path Parameters
sourceOrg
required
string
Example: source-org

The name of the source org.

Request Body schema: application/json

The object mapping request body.

objectType
required
string
Enum: "ACCESS_PROFILE" "ACCESS_REQUEST_CONFIG" "ATTR_SYNC_SOURCE_CONFIG" "AUTH_ORG" "CAMPAIGN_FILTER" "ENTITLEMENT" "FORM_DEFINITION" "GOVERNANCE_GROUP" "IDENTITY" "IDENTITY_OBJECT_CONFIG" "IDENTITY_PROFILE" "LIFECYCLE_STATE" "NOTIFICATION_TEMPLATE" "PASSWORD_POLICY" "PASSWORD_SYNC_GROUP" "PUBLIC_IDENTITIES_CONFIG" "ROLE" "RULE" "SEGMENT" "SERVICE_DESK_INTEGRATION" "SOD_POLICY" "SOURCE" "TAG" "TRANSFORM" "TRIGGER_SUBSCRIPTION" "WORKFLOW"

Type of the object the mapping value applies to, must be one from enum

jsonPath
required
string

JSONPath expression denoting the path within the object where the mapping value should be applied

sourceValue
required
string

Original value at the jsonPath location within the object

targetValue
required
string

Value to be assigned at the jsonPath location within the object

enabled
boolean
Default: false

Whether or not this object mapping is enabled

Responses

Request samples

Content type
application/json
{
  • "objectType": "GOVERNANCE_GROUP",
  • "jsonPath": "$.description",
  • "sourceValue": "Sample Governance Group",
  • "targetValue": "Sample Governance Group - Updated",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "objectMappingId": "3d6e0144-963f-4bd6-8d8d-d77b4e507ce4",
  • "objectType": "GOVERNANCE_GROUP",
  • "jsonPath": "$.description",
  • "sourceValue": "Sample Governance Group",
  • "targetValue": "Sample Governance Group - Updated",
  • "enabled": true,
  • "created": "2024-03-19T23:18:53.732Z",
  • "modified": "2024-03-19T23:18:53.732Z"
}

Deletes an object mapping

This deletes an existing object mapping. Source org should be "default" when deleting an object mapping that is not associated to any particular org. The request will need the following security scope:

  • sp:config-object-mapping:manage
Authorizations:
Personal Access Token
path Parameters
sourceOrg
required
string
Example: source-org

The name of the source org.

objectMappingId
required
string
Example: 3d6e0144-963f-4bd6-8d8d-d77b4e507ce4

The id of the object mapping to be deleted.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Bulk creates object mappings

This creates a set of object mappings (Max 25) between current org and source org. Source org should be "default" when creating object mappings that are not to be associated to any particular org. The request will need the following security scope:

  • sp:config-object-mapping:manage
Authorizations:
Personal Access Token
path Parameters
sourceOrg
required
string
Example: source-org

The name of the source org.

Request Body schema: application/json

The bulk create object mapping request body.

required
Array of objects (Object Mapping Request)

Responses

Request samples

Content type
application/json
{
  • "newObjectsMappings": [
    ]
}

Response samples

Content type
application/json
{
  • "addedObjects": [
    ]
}

Bulk updates object mappings

This updates a set of object mappings, only enabled and targetValue fields can be updated. Source org should be "default" when updating object mappings that are not associated to any particular org. The request will need the following security scope:

  • sp:config-object-mapping:manage
Authorizations:
Personal Access Token
path Parameters
sourceOrg
required
string
Example: source-org

The name of the source org.

Request Body schema: application/json

The object mapping request body.

required
object

Map of id of the object mapping to a JsonPatchOperation describing what to patch on that object mapping.

Responses

Request samples

Content type
application/json
{
  • "patches": {
    }
}

Response samples

Content type
application/json
{
  • "patchedObjects": [
    ]
}

List uploaded configurations

This API gets a list of existing uploaded configurations for the current tenant.

Authorizations:
Personal Access Token
query Parameters
filters
string
Example: filters=status eq "COMPLETE"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

status: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload a configuration

This API uploads a JSON configuration file into a tenant.

Configuration files can be managed and deployed via Configuration Hub by uploading a json file which contains configuration data. The JSON file should be the same as the one used by our import endpoints. The object types supported by upload configuration file functionality are the same as the ones supported by our regular backup functionality.

Refer to SaaS Configuration for more information about supported objects.

Authorizations:
Personal Access Token
Request Body schema: multipart/form-data

The body will consist of "data" which should contain the json file and name wish should be the name you want to assign to the uploaded file"

Example

data: "uploaded.json",
name: "A_NEW_UPLOADED_BACKUP"

Sample Upload File

{
  "version": 1,
  "tenant": "a-sample-tenant",
  "objects":
  [
    {
      "version": 1,
      "self":
        {
          "id": "0a59c7196d2917f8aa6d29686e6600fb",
          "type": "SOURCE",
          "name": "Extended Form"
        },
      "object":
        {
          "id": "0a59c7196d2917f8aa6d29686e6600fb",
          "name": "Extended Form",
          "type": "DelimitedFile",
          "connectorClass": "sailpoint.connector.DelimitedFileConnector",
          "connectorScriptName": "delimited-file-angularsc",
          "description": "Migrated app - Extended Form (original ID: 0a59c7196d2917f8aa6d29686e6600fb)",
          "deleteThreshold": 10,
          "provisionAsCsv": false,
          "owner":
            {
              "type": "IDENTITY",
              "id": "0a59c7196d2917f8816d29685fed00c3",
              "name": "slpt.services"
            },
          "connectorAttributes":
            {
              "beforemoveAccount": "Do Nothing",
              "beforemoverAccount": "Do Nothing",
              "busApp": "false",
              "file": "Empty",
              "filetransport": "local",
              "filterEmptyRecords": "true",
              "group.filetransport": "local",
              "group.filterEmptyRecords": "true",
              "group.partitionMode": "auto",
              "hasHeader": "true",
              "indexColumn": "ID",
              "isCaseInsensitiveMerge": "false",
              "isSortedByIndexColumn": "false",
              "loaProcess": "Do Nothing",
              "ltdProcess": "Do Nothing",
              "mergeRows": "false",
              "moverProcess": "Do Nothing",
              "moverRevocation": "Do Nothing",
              "nativeChangeDetectionAttributeScope": "entitlements",
              "nativeChangeDetectionEnabled": "false",
              "nativeChangeProcess": "Do Nothing",
              "parseType": "delimited",
              "partitionMode": "auto",
              "policyType": "Do Nothing",
              "rehireProcess": "Do Nothing",
              "reverseleaverProcess": "Do Nothing",
              "rtwloaProcess": "Do Nothing",
              "rtwltdProcess": "Do Nothing",
              "stopIfLineHasWrongColumnLength": "false",
              "templateApplication": "DelimitedFile Template",
              "terminationProcess": "Do Nothing"
            },
          "schemas":
            [],
          "provisioningPolicies":
            [],
          "features":
            [
              "DIRECT_PERMISSIONS",
              "NO_RANDOM_ACCESS",
              "DISCOVER_SCHEMA"
            ]
        }
    }
  ]

}

data
required
string <binary>

JSON file containing the objects to be imported.

name
required
string

Name that will be assigned to the uploaded configuration file.

Responses

Response samples

Content type
application/json
{
  • "jobId": "3469b87d-48ca-439a-868f-2160001da8c1",
  • "status": "COMPLETE",
  • "type": "BACKUP",
  • "tenant": "tenant-name",
  • "requesterName": "Requester Name",
  • "fileExists": true,
  • "created": "2021-05-11T22:23:16Z",
  • "modified": "2021-05-11T22:23:16Z",
  • "completed": "2021-05-11T22:23:16Z",
  • "name": "Backup Name",
  • "userCanDelete": false,
  • "isPartial": false,
  • "backupType": "MANUAL",
  • "options": {
    },
  • "hydrationStatus": "NOT_HYDRATED",
  • "totalObjectCount": 10,
  • "cloudStorageStatus": "SYNCED"
}

Get an uploaded configuration

This API gets an existing uploaded configuration for the current tenant.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 3d0fe04b-57df-4a46-a83b-8f04b0f9d10b

The id of the uploaded configuration.

Responses

Response samples

Content type
application/json
{
  • "jobId": "2ea830f3-2b14-4772-8a20-3d006742e419",
  • "status": "COMPLETE",
  • "type": "BACKUP",
  • "tenant": "someTenant",
  • "requesterName": "support",
  • "fileExists": true,
  • "created": "2024-02-20T22:08:31.064Z",
  • "modified": "2024-02-20T22:13:15.662Z",
  • "completed": "2024-02-20T22:08:31.689Z",
  • "name": "something new",
  • "userCanDelete": false,
  • "isPartial": false,
  • "backupType": "UPLOADED",
  • "hydrationStatus": "HYDRATED",
  • "totalObjectCount": 2
}

Delete an uploaded configuration

This API deletes an uploaded configuration based on Id.

On success, this endpoint will return an empty response.

The uploaded configuration id can be obtained from the response after a successful upload, or the list uploaded configurations endpoint.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 3d0fe04b-57df-4a46-a83b-8f04b0f9d10b

The id of the uploaded configuration.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Connectors

Use this API to implement connector functionality. With this functionality in place, administrators can view available connectors.

Connectors are the bridges Identity Security Cloud uses to communicate with and aggregate data from sources. For example, if it is necessary to set up a connection between Identity Security Cloud and the Active Directory source, a connector can bridge the two and enable Identity Security Cloud to synchronize data between the systems. This ensures account entitlements and states are correct throughout the organization.

In Identity Security Cloud, administrators can use the Connections drop-down menu and select Sources to view the available source connectors.

Refer to Identity Security Cloud Connectors for more information about the connectors available in Identity Security Cloud.

Refer to SaaS Connectivity for more information about the SaaS custom connectors that do not need VAs (virtual appliances) to communicate with their sources.

Refer to Managing Sources for more information about using connectors in Identity Security Cloud.

Get connector by script name

Fetches a connector that using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

query Parameters
locale
string
Enum: "de" "no" "fi" "sv" "ru" "pt" "ko" "zh-TW" "en" "it" "fr" "zh-CN" "hu" "es" "cs" "ja" "pl" "da" "nl"
Example: locale=de

The locale to apply to the config. If no viable locale is given, it will default to "en"

Responses

Response samples

Content type
application/json
{
  • "name": "name",
  • "type": "ServiceNow",
  • "className": "class name",
  • "scriptName": "servicenow",
  • "applicationXml": "<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE Application PUBLIC \"sailpoint.dtd\" \"sailpoint.dtd\">\n<Application connector=\"sailpoint.connector.OpenConnectorAdapter\" name=\"custom Atlassian Suite - Cloud\" type=\"custom Atlassian Suite - Cloud\"/>\n",
  • "correlationConfigXml": "<?xml version='1.0' encoding='UTF-8'?>\n<!-- Copyright (C) 2021 SailPoint Technologies, Inc. All rights reserved. -->\n\n<!DOCTYPE CorrelationConfig PUBLIC \"sailpoint.dtd\" \"sailpoint.dtd\">\n\n<CorrelationConfig name=\"custom Atlassian Suite - Cloud Account Correlation Config\">\n\t<AttributeAssignments>\n\t\t<Filter operation=\"EQ\" property=\"email\" value=\"mail\"/>\n\t\t<Filter operation=\"EQ\" property=\"empId\" value=\"employeeNumber\"/>\n\t\t<Filter operation=\"EQ\" property=\"displayName\" value=\"cn\"/>\n\t</AttributeAssignments>\n</CorrelationConfig>\n",
  • "sourceConfigXml": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><!-- Copyright (C) 2023 SailPoint Technologies, Inc. All rights reserved. --><Form xmlns=\"http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd\" connectorName=\"custom Atlassian Suite - Cloud\" directConnect=\"true\" fileUpload=\"true\" name=\"Custom Atlassian Suite - Cloud\" status=\"released\" type=\"SourceConfig\">\n <BaseConfig>\n <Field maxFiles=\"10\" maxSize=\"300\" name=\"fileUpload\" supportedExtensions=\"jar\" type=\"fileupload\" validateJSON=\"false\"/>\n </BaseConfig>\n \n\n \n</Form>",
  • "sourceConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><!-- Copyright (C) 2023 SailPoint Technologies, Inc. All rights reserved. --><Form xmlns=\"http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd\" connectorName=\"custom Atlassian Suite - Cloud\" directConnect=\"true\" fileUpload=\"true\" name=\"Custom Atlassian Suite - Cloud\" status=\"released\" type=\"SourceConfig\">\n <BaseConfig>\n <Field maxFiles=\"10\" maxSize=\"300\" name=\"fileUpload\" supportedExtensions=\"jar\" type=\"fileupload\" validateJSON=\"false\"/>\n </BaseConfig>\n \n\n \n</Form>",
  • "sourceConfigFrom": "sp-connect",
  • "s3Location": "custom-connector/scriptname",
  • "uploadedFiles": [
    ],
  • "fileUpload": true,
  • "directConnect": true,
  • "translationProperties": {
    },
  • "connectorMetadata": {
    },
  • "status": "RELEASED"
}

Delete connector by script name

Delete a custom connector that using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Update connector by script name

This API updates a custom connector by script name using JSON Patch syntax.

The following fields are patchable:

  • connectorMetadata

  • applicationXml

  • correlationConfigXml

  • sourceConfigXml

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Request Body schema: application/json-patch+json

A list of connector detail update operations

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "name": "name",
  • "type": "ServiceNow",
  • "className": "class name",
  • "scriptName": "servicenow",
  • "applicationXml": "<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE Application PUBLIC \"sailpoint.dtd\" \"sailpoint.dtd\">\n<Application connector=\"sailpoint.connector.OpenConnectorAdapter\" name=\"custom Atlassian Suite - Cloud\" type=\"custom Atlassian Suite - Cloud\"/>\n",
  • "correlationConfigXml": "<?xml version='1.0' encoding='UTF-8'?>\n<!-- Copyright (C) 2021 SailPoint Technologies, Inc. All rights reserved. -->\n\n<!DOCTYPE CorrelationConfig PUBLIC \"sailpoint.dtd\" \"sailpoint.dtd\">\n\n<CorrelationConfig name=\"custom Atlassian Suite - Cloud Account Correlation Config\">\n\t<AttributeAssignments>\n\t\t<Filter operation=\"EQ\" property=\"email\" value=\"mail\"/>\n\t\t<Filter operation=\"EQ\" property=\"empId\" value=\"employeeNumber\"/>\n\t\t<Filter operation=\"EQ\" property=\"displayName\" value=\"cn\"/>\n\t</AttributeAssignments>\n</CorrelationConfig>\n",
  • "sourceConfigXml": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><!-- Copyright (C) 2023 SailPoint Technologies, Inc. All rights reserved. --><Form xmlns=\"http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd\" connectorName=\"custom Atlassian Suite - Cloud\" directConnect=\"true\" fileUpload=\"true\" name=\"Custom Atlassian Suite - Cloud\" status=\"released\" type=\"SourceConfig\">\n <BaseConfig>\n <Field maxFiles=\"10\" maxSize=\"300\" name=\"fileUpload\" supportedExtensions=\"jar\" type=\"fileupload\" validateJSON=\"false\"/>\n </BaseConfig>\n \n\n \n</Form>",
  • "sourceConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><!-- Copyright (C) 2023 SailPoint Technologies, Inc. All rights reserved. --><Form xmlns=\"http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd\" connectorName=\"custom Atlassian Suite - Cloud\" directConnect=\"true\" fileUpload=\"true\" name=\"Custom Atlassian Suite - Cloud\" status=\"released\" type=\"SourceConfig\">\n <BaseConfig>\n <Field maxFiles=\"10\" maxSize=\"300\" name=\"fileUpload\" supportedExtensions=\"jar\" type=\"fileupload\" validateJSON=\"false\"/>\n </BaseConfig>\n \n\n \n</Form>",
  • "sourceConfigFrom": "sp-connect",
  • "s3Location": "custom-connector/scriptname",
  • "uploadedFiles": [
    ],
  • "fileUpload": true,
  • "directConnect": true,
  • "translationProperties": {
    },
  • "connectorMetadata": {
    },
  • "status": "RELEASED"
}

Get connector list

Fetches list of connectors that have 'RELEASED' status using filtering and pagination.

Authorizations:
Personal Access Token
query Parameters
filters
string
Example: filters=directConnect eq "true"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

name: sw, co

type: sw, co, eq

directConnect: eq

category: eq

features: ca

labels: ca

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

locale
string
Enum: "de" "no" "fi" "sv" "ru" "pt" "ko" "zh-TW" "en" "it" "fr" "zh-CN" "hu" "es" "cs" "ja" "pl" "da" "nl"
Example: locale=de

The locale to apply to the config. If no viable locale is given, it will default to "en"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create custom connector

Create custom connector.

Authorizations:
Personal Access Token
Request Body schema: application/json
name
required
string

The connector name. Need to be unique per tenant. The name will able be used to derive a url friendly unique scriptname that will be in response. Script name can then be used for all update endpoints

type
string

The connector type. If not specified will be defaulted to 'custom '+name

className
required
string

The connector class name. If you are implementing openconnector standard (what is recommended), then this need to be set to sailpoint.connector.OpenConnectorAdapter

directConnect
boolean
Default: true

true if the source is a direct connect source

status
string
Enum: "DEVELOPMENT" "DEMO" "RELEASED"

The connector status

Responses

Request samples

Content type
application/json
{
  • "name": "custom connector",
  • "type": "custom connector type",
  • "className": "sailpoint.connector.OpenConnectorAdapter",
  • "directConnect": true,
  • "status": "RELEASED"
}

Response samples

Content type
application/json
{
  • "name": "name",
  • "type": "ServiceNow",
  • "scriptName": "servicenow",
  • "className": "sailpoint.connector.OpenConnectorAdapter",
  • "features": [
    ],
  • "directConnect": true,
  • "connectorMetadata": {
    },
  • "status": "RELEASED"
}

Get connector source configuration

Fetches a connector's source config using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Update connector source configuration

Update a connector's source config using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Request Body schema: multipart/form-data
file
required
string <binary>

connector source config xml file

Responses

Response samples

Content type
application/json
{
  • "message": "unsupported xsd version, please ensure latest xsd version http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd is used for source config",
  • "scriptName": "servicenow",
  • "updatedFiles": [
    ],
  • "status": "ERROR"
}

Get connector translations

Fetches a connector's translations using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. Scriptname is the unique id generated at connector creation.

locale
required
string
Enum: "de" "no" "fi" "sv" "ru" "pt" "ko" "zh-TW" "en" "it" "fr" "zh-CN" "hu" "es" "cs" "ja" "pl" "da" "nl"
Example: de

The locale to apply to the config. If no viable locale is given, it will default to "en"

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Update connector translations

Update a connector's translations using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. Scriptname is the unique id generated at connector creation.

locale
required
string
Enum: "de" "no" "fi" "sv" "ru" "pt" "ko" "zh-TW" "en" "it" "fr" "zh-CN" "hu" "es" "cs" "ja" "pl" "da" "nl"
Example: de

The locale to apply to the config. If no viable locale is given, it will default to "en"

Request Body schema: multipart/form-data
object

Responses

Response samples

Content type
application/json
{
  • "message": "unsupported xsd version, please ensure latest xsd version http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd is used for source config",
  • "scriptName": "servicenow",
  • "updatedFiles": [
    ],
  • "status": "ERROR"
}

Get connector source template

Fetches a connector's source template using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Update connector source template

Update a connector's source template using its script name.

Authorizations:
Personal Access Token
path Parameters
scriptName
required
string
Example: aScriptName

The scriptName value of the connector. ScriptName is the unique id generated at connector creation.

Request Body schema: multipart/form-data
file
required
string <binary>

connector source template xml file

Responses

Response samples

Content type
application/json
{
  • "message": "unsupported xsd version, please ensure latest xsd version http://www.sailpoint.com/xsd/sailpoint_form_2_0.xsd is used for source config",
  • "scriptName": "servicenow",
  • "updatedFiles": [
    ],
  • "status": "ERROR"
}

Global Tenant Security Settings

Use this API to implement and customize global tenant security settings. With this functionality in place, administrators can manage the global security settings that a tenant/org has. This API can be used to configure the networks and Geographies allowed to access Identity Security Cloud URLs.

Get security network configuration.

This API returns the details of an org's network auth configuration.

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
{
  • "range": [
    ],
  • "geolocation": [
    ],
  • "whitelisted": true
}

Create security network configuration.

This API returns the details of an org's network auth configuration. Requires security scope of: 'sp:auth-org:manage'

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json

Network configuration creation request body. The following constraints ensure the request body conforms to certain logical guidelines, which are:

  1. Each string element in the range array must be a valid ip address or ip subnet mask.
  2. Each string element in the geolocation array must be 2 characters, and they can only be uppercase letters.
range
Array of strings or null

The collection of ip ranges.

geolocation
Array of strings or null

The collection of country codes.

whitelisted
boolean
Default: false

Denotes whether the provided lists are whitelisted or blacklisted for geo location.

Responses

Request samples

Content type
application/json
{
  • "range": [
    ],
  • "geolocation": [
    ],
  • "whitelisted": true
}

Response samples

Content type
application/json
{
  • "range": [
    ],
  • "geolocation": [
    ],
  • "whitelisted": true
}

Update security network configuration.

This API updates an existing network configuration for an org using PATCH Requires security scope of: 'sp:auth-org:manage'

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json-patch+json

A list of auth org network configuration update operations according to the JSON Patch standard. Ensures that the patched Network Config conforms to certain logical guidelines, which are:

  1. Each string element in the range array must be a valid ip address or ip subnet mask.
  2. Each string element in the geolocation array must be 2 characters, and they can only be uppercase letters.
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "range": [
    ],
  • "geolocation": [
    ],
  • "whitelisted": true
}

Get auth org lockout configuration.

This API returns the details of an org's lockout auth configuration.

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
{
  • "maximumAttempts": 5,
  • "lockoutDuration": 15,
  • "lockoutWindow": 5
}

Update auth org lockout configuration

This API updates an existing lockout configuration for an org using PATCH

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json-patch+json

A list of auth org lockout configuration update operations according to the JSON Patch standard. Ensures that the patched Lockout Config conforms to certain logical guidelines, which are: 1. maximumAttempts >= 1 && maximumAttempts <= 15 2. lockoutDuration >= 5 && lockoutDuration <= 60 3. lockoutWindow >= 5 && lockoutDuration <= 60

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "maximumAttempts": 5,
  • "lockoutDuration": 15,
  • "lockoutWindow": 5
}

Get service provider configuration.

This API returns the details of an org's service provider auth configuration.

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "bypassIdp": true,
  • "samlConfigurationValid": true,
  • "federationProtocolDetails": [
    ]
}

Update service provider configuration

This API updates an existing service provider configuration for an org using PATCH.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json-patch+json

A list of auth org service provider configuration update operations according to the JSON Patch standard. Note: /federationProtocolDetails/0 is IdpDetails /federationProtocolDetails/1 is SpDetails Ensures that the patched ServiceProviderConfig conforms to certain logical guidelines, which are:

  1. Do not add or remove any elements in the federation protocol details in the service provider configuration.
  2. Do not modify, add, or delete the service provider details element in the federation protocol details.
  3. If this is the first time the patched ServiceProviderConfig enables Remote IDP sign-in, it must also include IDPDetails.
  4. If the patch enables Remote IDP sign in, the entityID in the IDPDetails cannot be null. IDPDetails must include an entityID.
  5. Any JIT configuration update must be valid.

Just in time configuration update must be valid when enabled. This includes:

  • A Source ID
  • Source attribute mappings
  • Source attribute maps have all the required key values (firstName, lastName, email)
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "enabled": true,
  • "bypassIdp": true,
  • "samlConfigurationValid": true,
  • "federationProtocolDetails": [
    ]
}

Get auth org session configuration.

This API returns the details of an org's session auth configuration.

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
{
  • "maxIdleTime": 15,
  • "rememberMe": true,
  • "maxSessionTime": 45
}

Update auth org session configuration

This API updates an existing session configuration for an org using PATCH.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json-patch+json

A list of auth org session configuration update operations according to the JSON Patch standard.

Ensures that the patched Session Config conforms to certain logical guidelines, which are: 1. maxSessionTime >= 1 && maxSessionTime <= 10080 (1 week) 2. maxIdleTime >= 1 && maxIdleTime <= 1440 (1 day) 3. maxSessionTime must have a greater duration than maxIdleTime.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "maxIdleTime": 15,
  • "rememberMe": true,
  • "maxSessionTime": 45
}

Identity Profiles

Use this API to implement identity profile functionality. With this functionality in place, administrators can view identity profiles and their configurations.

Identity profiles represent the configurations that can be applied to identities as a way of granting them a set of security and access, as well as defining the mappings between their identity attributes and their source attributes.

In Identity Security Cloud, administrators can use the Identities drop-down menu and select Identity Profiles to view the list of identity profiles. This list shows some details about each identity profile, along with its status. They can select an identity profile to view its settings, its mappings between identity attributes and correlating source account attributes, and its provisioning settings.

Refer to Creating Identity Profiles for more information about identity profiles.

List identity profiles

Get a list of identity profiles, based on the specified query parameters.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, ne, ge, gt, in, le, sw

name: eq, ne, ge, gt, in, le, sw

priority: eq, ne

sorters
string <comma-separated>
Example: sorters=id,name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: id, name, priority, created, modified, owner.id, owner.name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create identity profile

Creates an identity profile.

Authorizations:
Personal Access Token
Request Body schema: application/json
name
required
string or null

Name of the Object

description
string or null

Identity profile's description.

object or null

Identity profile's owner.

priority
integer <int64>

Identity profile's priority.

required
object
identityRefreshRequired
boolean
Default: false

Set this value to 'True' if an identity refresh is necessary. You would typically want to trigger an identity refresh when a change has been made on the source.

identityCount
integer <int32>

Number of identities belonging to the identity profile.

object (Identity Attribute Config)

Defines all the identity attribute mapping configurations. This defines how to generate or collect data for each identity attributes in identity refresh process.

object or null (Identity Exception Report Reference)
hasTimeBasedAttr
boolean
Default: false

Indicates the value of requiresPeriodicRefresh attribute for the identity profile.

Responses

Request samples

Content type
application/json
{
  • "name": "aName",
  • "description": "My custom flat file profile",
  • "owner": {
    },
  • "priority": 10,
  • "authoritativeSource": {
    },
  • "identityRefreshRequired": true,
  • "identityCount": 8,
  • "identityAttributeConfig": {
    },
  • "identityExceptionReportReference": {
    },
  • "hasTimeBasedAttr": true
}

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "description": "My custom flat file profile",
  • "owner": {
    },
  • "priority": 10,
  • "authoritativeSource": {
    },
  • "identityRefreshRequired": true,
  • "identityCount": 8,
  • "identityAttributeConfig": {
    },
  • "identityExceptionReportReference": {
    },
  • "hasTimeBasedAttr": true
}

Delete identity profiles

This deletes multiple Identity Profiles via a list of supplied IDs.

On success, this endpoint will return a reference to the bulk delete task result.

The following rights are required to access this endpoint: idn:identity-profile:delete

Authorizations:
Personal Access Token
Request Body schema: application/json

Identity Profile bulk delete request body.

Array
string

Responses

Request samples

Content type
application/json
[
  • "2c9180867b2a34e0017b3078d60b0699",
  • "2c9180867b2a34e0017b3078d60b0698"
]

Response samples

Content type
application/json
{
  • "id": "ff8081814d977c21014da056804a0af3",
  • "name": "Background Object Terminator c8f030f2-b1a6-4e33-99e8-6935bc18735d",
  • "description": "Generic task for terminating data in the overlay, used by the TerminationService.",
  • "launcher": "support",
  • "completed": "Mon Aug 21 14:57:39 CDT 2023",
  • "launched": "Mon Aug 21 14:55:39 CDT 2023",
  • "completionStatus": "Success"
}

Export identity profiles

This exports existing identity profiles in the format specified by the sp-config service.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=id eq "ef38f94347e94562b5bb8424a56397d8"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, ne

name: eq, ne

priority: eq, ne

sorters
string <comma-separated>
Example: sorters=id,name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: id, name, priority

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Import identity profiles

This imports previously exported identity profiles.

Authorizations:
Personal Access Token
Request Body schema: application/json

Previously exported Identity Profiles.

Array
version
integer <int32>

Version or object from the target service.

object

Self block for exported object.

object (IdentityProfile-2)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "infos": [
    ],
  • "warnings": [
    ],
  • "errors": [
    ],
  • "importedObjects": [
    ]
}

Generate identity profile preview

Use this API to generate a non-persisted preview of the identity object after applying IdentityAttributeConfig sent in request body. This API only allows accountAttribute, reference and rule transform types in the IdentityAttributeConfig sent in the request body.

Authorizations:
Personal Access Token
Request Body schema: application/json

Identity Preview request body.

identityId
string <uuid>

The Identity id

object (Identity Attribute Config)

Defines all the identity attribute mapping configurations. This defines how to generate or collect data for each identity attributes in identity refresh process.

Responses

Request samples

Content type
application/json
{
  • "identityId": "2c9180857893f12901789445619b0366",
  • "identityAttributeConfig": {
    }
}

Response samples

Content type
application/json
{
  • "identity": {
    },
  • "previewAttributes": [
    ]
}

Get identity profile

Get a single identity profile by ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string <uuid>
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

Responses

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "description": "My custom flat file profile",
  • "owner": {
    },
  • "priority": 10,
  • "authoritativeSource": {
    },
  • "identityRefreshRequired": true,
  • "identityCount": 8,
  • "identityAttributeConfig": {
    },
  • "identityExceptionReportReference": {
    },
  • "hasTimeBasedAttr": true
}

Delete identity profile

Delete an identity profile by ID. On success, this endpoint will return a reference to the bulk delete task result.

Authorizations:
Personal Access Token
path Parameters
identity-profile-id
required
string <uuid>
Example: ef38f94347e94562b5bb8424a56397d8

Identity profile ID.

Responses

Response samples

Content type
application/json
{
  • "id": "ff8081814d977c21014da056804a0af3",
  • "name": "Background Object Terminator c8f030f2-b1a6-4e33-99e8-6935bc18735d",
  • "description": "Generic task for terminating data in the overlay, used by the TerminationService.",
  • "launcher": "support",
  • "completed": "Mon Aug 21 14:57:39 CDT 2023",
  • "launched": "Mon Aug 21 14:55:39 CDT 2023",
  • "completionStatus": "Success"
}

Update identity profile

Update a specified identity profile with this PATCH request.

You cannot update these fields:

  • id
  • created
  • modified
  • identityCount
  • identityRefreshRequired
  • Authoritative Source and Identity Attribute Configuration cannot be modified at the same time.
Authorizations:
Personal Access Token
path Parameters
identity-profile-id
required
string <uuid>
Example: ef38f94347e94562b5bb8424a56397d8

Identity profile ID.

Request Body schema: application/json-patch+json

List of identity profile update operations according to the JSON Patch standard.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "description": "My custom flat file profile",
  • "owner": {
    },
  • "priority": 10,
  • "authoritativeSource": {
    },
  • "identityRefreshRequired": true,
  • "identityCount": 8,
  • "identityAttributeConfig": {
    },
  • "identityExceptionReportReference": {
    },
  • "hasTimeBasedAttr": true
}

Get default identity attribute config

This returns the default identity attribute config.

Authorizations:
Personal Access Token
path Parameters
identity-profile-id
required
string <uuid>
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

The Identity Profile ID.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "attributeTransforms": [
    ]
}

Process identities under profile

Process identities under the profile This operation should not be used to schedule your own identity processing or to perform system wide identity refreshes. The system will use a combination of event-based processing and scheduled processing that runs every day at 8:00 AM and 8:00 PM in the tenant's timezone to keep your identities synchronized. This should only be run on identity profiles that have the identityRefreshRequired attribute set to true. If identityRefreshRequired is false, then there is no benefit to running this operation. Typically, this operation is performed when a change is made to the identity profile or its related lifecycle states that requires a refresh. This operation will perform the following activities on all identities under the identity profile.

  1. Updates identity attribute according to the identity profile mappings. 2. Determines the identity's correct manager through manager correlation. 3. Updates the identity's access according to their assigned lifecycle state. 4. Updates the identity's access based on role assignment criteria.
Learn more about manually processing identities here
Authorizations:
Personal Access Token
path Parameters
identity-profile-id
required
string <uuid>
Example: ef38f94347e94562b5bb8424a56397d8

The Identity Profile ID to be processed

Responses

Response samples

Content type
application/json
{ }

Lifecycle States

Use this API to implement and customize lifecycle state functionality. With this functionality in place, administrators can create and configure custom lifecycle states for use across their organizations, which is key to controlling which users have access, when they have access, and the access they have.

A lifecycle state describes a user's status in a company. For example, two lifecycle states come by default with Identity Security Cloud: 'Active' and 'Inactive.' When an active employee takes an extended leave of absence from a company, his or her lifecycle state may change to 'Inactive,' for security purposes. The inactive employee would lose access to all the applications, sources, and sensitive data during the leave of absence, but when the employee returns and becomes active again, all that access would be restored. This saves administrators the time that would otherwise be spent provisioning the employee's access to each individual tool, reviewing the employee's certification history, etc.

Administrators can create a variety of custom lifecycle states. Refer to Planning New Lifecycle States for some custom lifecycle state ideas.

Administrators must define the criteria for being in each lifecycle state, and they must define how Identity Security Cloud manages users' access to apps and sources for each lifecycle state.

In Identity Security Cloud, administrators can manage lifecycle states by going to Admin > Identities > Identity Profile, selecting the identity profile whose lifecycle states they want to manage, selecting the 'Provisioning' tab, and using the left panel to either select the lifecycle state they want to modify or create a new lifecycle state.

In the 'Provisioning' tab, administrators can make the following access changes to an identity profile's lifecycle state:

  • Enable/disable the lifecycle state for the identity profile.

  • Enable/disable source accounts for the identity profile's lifecycle state.

  • Add existing access profiles to grant to the identity profiles in that lifecycle state.

  • Create a new access profile to grant to the identity profile in that lifecycle state.

Access profiles granted in a previous lifecycle state are automatically revoked when the identity moves to a new lifecycle state. To maintain access across multiple lifecycle states, administrators must grant the access profiles in each lifecycle state. For example, if an administrator wants users with the 'HR Employee' identity profile to maintain their building access in both the 'Active' and 'Leave of Absence' lifecycle states, the administrator must grant the access profile for that building access to both lifecycle states.

During scheduled refreshes, Identity Security Cloud evaluates lifecycle states to determine whether their assigned identities have the access defined in the lifecycle states' access profiles. If the identities are missing access, Identity Security Cloud provisions that access.

Administrators can also use the 'Provisioning' tab to configure email notifications for Identity Security Cloud to send whenever an identity with that identity profile has a lifecycle state change. Refer to Configuring Lifecycle State Notifications for more information on how to do so.

An identity's lifecycle state can have four different statuses: the lifecycle state's status can be 'Active,' it can be 'Not Set,' it can be 'Not Valid,' or it 'Does Not Match Technical Name Case.' Refer to Moving Identities into Lifecycle States for more information about these different lifecycle state statuses.

Refer to Setting Up Lifecycle States for more information about lifecycle states.

Set lifecycle state

Use this API to set/update an identity's lifecycle state to the one provided and update the corresponding identity profile.

Authorizations:
Personal Access Token
path Parameters
identity-id
required
string
Example: 2c9180857893f1290178944561990364

ID of the identity to update.

Request Body schema: application/json
lifecycleStateId
string

ID of the lifecycle state to set.

Responses

Request samples

Content type
application/json
{
  • "lifecycleStateId": "2c9180877a86e408017a8c19fefe046c"
}

Response samples

Content type
application/json
{
  • "accountActivityId": "2c9180837ab5b716017ab7c6c9ef1e20"
}

Lists lifecyclestates

Use this endpoint to list all lifecycle states by their associated identity profiles.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

sorters
string <comma-separated>
Example: sorters=created,modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, priority, created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create lifecycle state

Use this endpoint to create a lifecycle state.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

Request Body schema: application/json

Lifecycle state to be created.

name
required
string or null

Name of the Object

enabled
boolean
Default: false

Indicates whether the lifecycle state is enabled or disabled.

technicalName
required
string

The lifecycle state's technical name. This is for internal use.

description
string

Lifecycle state's description.

object (Email Notification Option)

This is used for representing email configuration for a lifecycle state

Array of objects (Account Action)
accessProfileIds
Array of strings unique

List of unique access-profile IDs that are associated with the lifecycle state.

identityState
string or null

The lifecycle state's associated identity state. This field is generally 'null'.

Responses

Request samples

Content type
application/json
{
  • "name": "aName",
  • "enabled": true,
  • "technicalName": "Technical Name",
  • "description": "Lifecycle description",
  • "emailNotificationOption": {
    },
  • "accountActions": [
    ],
  • "accessProfileIds": [
    ],
  • "identityState": null
}

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "enabled": true,
  • "technicalName": "Technical Name",
  • "description": "Lifecycle description",
  • "identityCount": 42,
  • "emailNotificationOption": {
    },
  • "accountActions": [
    ],
  • "accessProfileIds": [
    ],
  • "identityState": null
}

Get lifecycle state

Use this endpoint to get a lifecycle state by its ID and its associated identity profile ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

lifecycle-state-id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Lifecycle state ID.

Responses

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "enabled": true,
  • "technicalName": "Technical Name",
  • "description": "Lifecycle description",
  • "identityCount": 42,
  • "emailNotificationOption": {
    },
  • "accountActions": [
    ],
  • "accessProfileIds": [
    ],
  • "identityState": null
}

Update lifecycle state

Use this endpoint to update individual lifecycle state fields, using the JSON Patch standard.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

lifecycle-state-id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Lifecycle state ID.

Request Body schema: application/json-patch+json

A list of lifecycle state update operations according to the JSON Patch standard.

The following fields can be updated:

  • enabled
  • description
  • accountActions
  • accessProfileIds
  • emailNotificationOption
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "name": "aName",
  • "created": "2015-05-28T14:07:17Z",
  • "modified": "2015-05-28T14:07:17Z",
  • "enabled": true,
  • "technicalName": "Technical Name",
  • "description": "Lifecycle description",
  • "identityCount": 42,
  • "emailNotificationOption": {
    },
  • "accountActions": [
    ],
  • "accessProfileIds": [
    ],
  • "identityState": null
}

Delete lifecycle state

Use this endpoint to delete the lifecycle state by its ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
identity-profile-id
required
string
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

Identity profile ID.

lifecycle-state-id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Lifecycle state ID.

Responses

Response samples

Content type
application/json
{
  • "type": "LIFECYCLE_STATE",
  • "id": 12345,
  • "name": "Contractor Lifecycle"
}

Managed Clients

Use this API to implement managed client functionality. With this functionality in place, administrators can modify and delete existing managed clients, create new ones, and view and make changes to their log configurations.

Get managed clients

List managed clients.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=name eq "client name"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq

name: eq

clientId: eq

clusterId: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create managed client

Create a new managed client. The API returns a result that includes the managed client ID.

Authorizations:
Personal Access Token
Request Body schema: application/json
clusterId
required
string

Cluster ID that the ManagedClient is linked to

description
string or null

description for the ManagedClient to create

name
string or null

name for the ManagedClient to create

type
string or null

Type of the ManagedClient (VA, CCG) to create

Responses

Request samples

Content type
application/json
{
  • "clusterId": "aClusterId",
  • "description": "A short description of the ManagedClient",
  • "name": "aName",
  • "type": "VA"
}

Response samples

Content type
application/json
{
  • "id": "2c9180878eaf4204018eb019c3570003",
  • "alertKey": "CLIENT_STATUS_NOT_CONFIGURED",
  • "apiGatewayBaseUrl": "string",
  • "cookbook": "string",
  • "ccId": 2248,
  • "clientId": "00be54a2-bb6d-402f-9159-beb2d5319347",
  • "clusterId": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "description": "A short description of the ManagedClient",
  • "ipAddress": "123.456.78.90",
  • "lastSeen": "2020-01-01T00:00:00.000000Z",
  • "name": "aName",
  • "sinceLastSeen": 15000,
  • "status": "NORMAL",
  • "type": "VA",
  • "clusterType": "idn",
  • "vaDownloadUrl": "aUrl",
  • "vaVersion": "va-megapod-useast1-610-1621372012",
  • "secret": "ef878e15eaa8c8d3e2fa52f41125e2a0eeadadc6a14f931a33ad3e1b62d56381",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "provisionStatus": "PROVISIONED"
}

Get managed client

Get managed client by ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 4440278c-0ce2-41ee-a0a9-f5cfd5e8d3b7

Managed client ID.

Responses

Response samples

Content type
application/json
{
  • "id": "2c9180878eaf4204018eb019c3570003",
  • "alertKey": "CLIENT_STATUS_NOT_CONFIGURED",
  • "apiGatewayBaseUrl": "string",
  • "cookbook": "string",
  • "ccId": 2248,
  • "clientId": "00be54a2-bb6d-402f-9159-beb2d5319347",
  • "clusterId": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "description": "A short description of the ManagedClient",
  • "ipAddress": "123.456.78.90",
  • "lastSeen": "2020-01-01T00:00:00.000000Z",
  • "name": "aName",
  • "sinceLastSeen": 15000,
  • "status": "NORMAL",
  • "type": "VA",
  • "clusterType": "idn",
  • "vaDownloadUrl": "aUrl",
  • "vaVersion": "va-megapod-useast1-610-1621372012",
  • "secret": "ef878e15eaa8c8d3e2fa52f41125e2a0eeadadc6a14f931a33ad3e1b62d56381",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "provisionStatus": "PROVISIONED"
}

Update managed client

Update an existing managed client.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 4440278c-0ce2-41ee-a0a9-f5cfd5e8d3b7

Managed client ID.

Request Body schema: application/json-patch+json

JSONPatch payload used to update the object.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c9180878eaf4204018eb019c3570003",
  • "alertKey": "CLIENT_STATUS_NOT_CONFIGURED",
  • "apiGatewayBaseUrl": "string",
  • "cookbook": "string",
  • "ccId": 2248,
  • "clientId": "00be54a2-bb6d-402f-9159-beb2d5319347",
  • "clusterId": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "description": "A short description of the ManagedClient",
  • "ipAddress": "123.456.78.90",
  • "lastSeen": "2020-01-01T00:00:00.000000Z",
  • "name": "aName",
  • "sinceLastSeen": 15000,
  • "status": "NORMAL",
  • "type": "VA",
  • "clusterType": "idn",
  • "vaDownloadUrl": "aUrl",
  • "vaVersion": "va-megapod-useast1-610-1621372012",
  • "secret": "ef878e15eaa8c8d3e2fa52f41125e2a0eeadadc6a14f931a33ad3e1b62d56381",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "provisionStatus": "PROVISIONED"
}

Delete managed client

Delete an existing managed client.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 4440278c-0ce2-41ee-a0a9-f5cfd5e8d3b7

Managed client ID.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get managed client status

Get a managed client's status, using its ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: aClientId

Managed client ID to get status for.

query Parameters
type
required
string or null (ManagedClientType)
Enum: "CCG" "VA" "INTERNAL" "IIQ_HARVESTER" null
Example: type=CCG

Managed client type to get status for.

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "status": "NORMAL",
  • "type": "CCG",
  • "timestamp": "2020-01-01T00:00:00.000000Z"
}

Managed Clusters

Use this API to implement managed cluster functionality. With this functionality in place, administrators can modify and delete existing managed clients, get their statuses, and create new ones.

Get managed clusters

List current organization's managed clusters, based on request context.

Authorizations:
Personal Access Token
query Parameters
offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=operational eq "operation"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

operational: eq

name: eq

type: eq

status: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create create managed cluster

Create a new Managed Cluster. The API returns a result that includes the managed cluster ID.

Authorizations:
Personal Access Token
Request Body schema: application/json
name
required
string

ManagedCluster name

type
string (ManagedClusterTypes)
Enum: "idn" "iai" "spConnectCluster" "sqsCluster" "das-rc" "das-pc" "das-dc" "pag" "das-am" "standard"

The Type of Cluster:

  • idn - IDN VA type
  • iai - IAI harvester VA
  • spConnectCluster - Saas 2.0 connector cluster (this should be one per org)
  • sqsCluster - This should be unused
  • das-rc - Data Access Security Resources Collector
  • das-pc - Data Access Security Permissions Collector
  • das-dc - Data Access Security Data Classification Collector
  • pag - Privilege Action Gateway VA
  • das-am - Data Access Security Activity Monitor
  • standard - Standard Cluster type for running multiple products
object

ManagedProcess configuration map

description
string or null

ManagedCluster description

Responses

Request samples

Content type
application/json
{
  • "name": "Managed Cluster Name",
  • "type": "idn",
  • "configuration": {
    },
  • "description": "A short description of the managed cluster."
}

Response samples

Content type
application/json
{
  • "id": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "name": "Managed Cluster Name",
  • "pod": "megapod-useast1",
  • "org": "denali",
  • "type": "idn",
  • "configuration": {
    },
  • "keyPair": {
    },
  • "attributes": {
    },
  • "description": "A short description of the managed cluster.",
  • "redis": {
    },
  • "clientType": "CCG",
  • "ccgVersion": "v01",
  • "pinnedConfig": false,
  • "logConfiguration": {
    },
  • "operational": false,
  • "status": "NORMAL",
  • "publicKeyCertificate": "-----BEGIN CERTIFICATE-----TCCAb2gAwIBAgIBADANBgkqhkiG9w0BAQsFADAuMQ0wCwYDVQQD-----END CERTIFICATE-----",
  • "publicKeyThumbprint": "obc6pLiulGbtZ",
  • "publicKey": "-----BEGIN PUBLIC KEY-----jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3WgnsxP52MDgBTfHR+5n4-----END PUBLIC KEY-----",
  • "encryptionConfiguration": {
    },
  • "alertKey": "LIMITED_RESOURCES",
  • "clientIds": [
    ],
  • "serviceCount": 6,
  • "ccId": "1533",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "lastReleaseNotifiedAt": "2025-03-11T07:00:13.729721Z",
  • "updatePreferences": {
    },
  • "currentInstalledReleaseVersion": "123.1",
  • "updatePackage": "123.1.2",
  • "isOutOfDateNotifiedAt": "2025-03-11T07:00:13.734393Z",
  • "consolidatedHealthIndicatorsStatus": "ERROR"
}

Get managed cluster

Get a managed cluster by ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180897de347a2017de8859e8c5039

Managed cluster ID.

Responses

Response samples

Content type
application/json
{
  • "id": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "name": "Managed Cluster Name",
  • "pod": "megapod-useast1",
  • "org": "denali",
  • "type": "idn",
  • "configuration": {
    },
  • "keyPair": {
    },
  • "attributes": {
    },
  • "description": "A short description of the managed cluster.",
  • "redis": {
    },
  • "clientType": "CCG",
  • "ccgVersion": "v01",
  • "pinnedConfig": false,
  • "logConfiguration": {
    },
  • "operational": false,
  • "status": "NORMAL",
  • "publicKeyCertificate": "-----BEGIN CERTIFICATE-----TCCAb2gAwIBAgIBADANBgkqhkiG9w0BAQsFADAuMQ0wCwYDVQQD-----END CERTIFICATE-----",
  • "publicKeyThumbprint": "obc6pLiulGbtZ",
  • "publicKey": "-----BEGIN PUBLIC KEY-----jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3WgnsxP52MDgBTfHR+5n4-----END PUBLIC KEY-----",
  • "encryptionConfiguration": {
    },
  • "alertKey": "LIMITED_RESOURCES",
  • "clientIds": [
    ],
  • "serviceCount": 6,
  • "ccId": "1533",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "lastReleaseNotifiedAt": "2025-03-11T07:00:13.729721Z",
  • "updatePreferences": {
    },
  • "currentInstalledReleaseVersion": "123.1",
  • "updatePackage": "123.1.2",
  • "isOutOfDateNotifiedAt": "2025-03-11T07:00:13.734393Z",
  • "consolidatedHealthIndicatorsStatus": "ERROR"
}

Update managed cluster

Update an existing managed cluster.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180897de347a2017de8859e8c5039

Managed cluster ID.

Request Body schema: application/json-patch+json

JSONPatch payload used to update the object.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "e1ff7bb24c934240bbf55e1aa39e41c5",
  • "name": "Managed Cluster Name",
  • "pod": "megapod-useast1",
  • "org": "denali",
  • "type": "idn",
  • "configuration": {
    },
  • "keyPair": {
    },
  • "attributes": {
    },
  • "description": "A short description of the managed cluster.",
  • "redis": {
    },
  • "clientType": "CCG",
  • "ccgVersion": "v01",
  • "pinnedConfig": false,
  • "logConfiguration": {
    },
  • "operational": false,
  • "status": "NORMAL",
  • "publicKeyCertificate": "-----BEGIN CERTIFICATE-----TCCAb2gAwIBAgIBADANBgkqhkiG9w0BAQsFADAuMQ0wCwYDVQQD-----END CERTIFICATE-----",
  • "publicKeyThumbprint": "obc6pLiulGbtZ",
  • "publicKey": "-----BEGIN PUBLIC KEY-----jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3WgnsxP52MDgBTfHR+5n4-----END PUBLIC KEY-----",
  • "encryptionConfiguration": {
    },
  • "alertKey": "LIMITED_RESOURCES",
  • "clientIds": [
    ],
  • "serviceCount": 6,
  • "ccId": "1533",
  • "createdAt": "2023-08-04T20:48:01.865Z",
  • "updatedAt": "2023-08-04T20:48:01.865Z",
  • "lastReleaseNotifiedAt": "2025-03-11T07:00:13.729721Z",
  • "updatePreferences": {
    },
  • "currentInstalledReleaseVersion": "123.1",
  • "updatePackage": "123.1.2",
  • "isOutOfDateNotifiedAt": "2025-03-11T07:00:13.734393Z",
  • "consolidatedHealthIndicatorsStatus": "ERROR"
}

Delete managed cluster

Delete an existing managed cluster.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c9180897de347a2017de8859e8c5039

Managed cluster ID.

query Parameters
removeClients
boolean
Default: false

Flag to determine the need to delete a cluster with clients.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get managed cluster log configuration

Get a managed cluster's log configuration.

Authorizations:
Personal Access Token
path Parameters
id
required
string <uuid>
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

ID of managed cluster to get log configuration for.

Responses

Response samples

Content type
application/json
{
  • "clientId": "3a38a51992e8445ab51a549c0a70ee66",
  • "durationMinutes": 120,
  • "expiration": "2024-11-06T01:31:08.013164Z",
  • "rootLevel": "INFO",
  • "logLevels": "INFO"
}

Update managed cluster log configuration

Update a managed cluster's log configuration. You may only specify one of durationMinutes or expiration, up to 1440 minutes (24 hours) in the future. If neither is specified, the default value for durationMinutes is 240.

Authorizations:
Personal Access Token
path Parameters
id
required
string <uuid>
Example: 2b838de9-db9b-abcf-e646-d4f274ad4238

ID of the managed cluster to update the log configuration for.

Request Body schema: application/json

Client log configuration for the given managed cluster.

One of
clientId
string

Log configuration's client ID

durationMinutes
integer <int32> [ 5 .. 1440 ]
Default: 240

Duration in minutes for log configuration to remain in effect before resetting to defaults.

rootLevel
required
string (StandardLevel)
Enum: "OFF" "FATAL" "ERROR" "WARN" "INFO" "DEBUG" "TRACE"

Standard Log4j log level

object (Log Level Spec)

Mapping of identifiers to Standard Log Level values

Responses

Request samples

Content type
application/json
Example
{
  • "clientId": "3a38a51992e8445ab51a549c0a70ee66",
  • "durationMinutes": 120,
  • "rootLevel": "INFO",
  • "logLevels": {
    }
}

Response samples

Content type
application/json
{
  • "clientId": "3a38a51992e8445ab51a549c0a70ee66",
  • "durationMinutes": 120,
  • "expiration": "2024-11-06T01:31:08.013164Z",
  • "rootLevel": "INFO",
  • "logLevels": "INFO"
}

MFA Configuration

Configure and test multifactor authentication (MFA) methods

Configuration of okta mfa method

This API returns the configuration of an Okta MFA method.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "mfaMethod": "okta-verify",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "d******Y",
  • "identityAttribute": "email"
}

Set okta mfa configuration

This API sets the configuration of an Okta MFA method.

Authorizations:
Personal Access Token
Request Body schema: application/json
mfaMethod
string or null

Mfa method name

enabled
boolean
Default: false

If MFA method is enabled.

host
string or null

The server host name or IP address of the MFA provider.

accessKey
string or null

The secret key for authenticating requests to the MFA provider.

identityAttribute
string or null

Optional. The name of the attribute for mapping IdentityNow identity to the MFA provider.

Responses

Request samples

Content type
application/json
{
  • "mfaMethod": "okta-verify",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "dk778Y3QlA5UqocYpdU3rEkzrK2D497y",
  • "identityAttribute": "email"
}

Response samples

Content type
application/json
{
  • "mfaMethod": "okta-verify",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "d******Y",
  • "identityAttribute": "email"
}

Configuration of duo mfa method

This API returns the configuration of an Duo MFA method.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "mfaMethod": "duo-web",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "d******Y",
  • "identityAttribute": "email",
  • "configProperties": {
    }
}

Set duo mfa configuration

This API sets the configuration of an Duo MFA method.

Authorizations:
Personal Access Token
Request Body schema: application/json
mfaMethod
string or null

Mfa method name

enabled
boolean
Default: false

If MFA method is enabled.

host
string or null

The server host name or IP address of the MFA provider.

accessKey
string or null

The secret key for authenticating requests to the MFA provider.

identityAttribute
string or null

Optional. The name of the attribute for mapping IdentityNow identity to the MFA provider.

object or null

A map with additional config properties for the given MFA method - duo-web.

Responses

Request samples

Content type
application/json
{
  • "mfaMethod": "duo-web",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "qw123Y3QlA5UqocYpdU3rEkzrK2D497y",
  • "identityAttribute": "email",
  • "configProperties": {
    }
}

Response samples

Content type
application/json
{
  • "mfaMethod": "duo-web",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "q******y",
  • "identityAttribute": "email",
  • "configProperties": {
    }
}

Configuration of kba mfa method

This API returns the KBA configuration for MFA.

Authorizations:
Personal Access Token
query Parameters
allLanguages
boolean
Example: allLanguages=allLanguages=true

Indicator whether the question text should be returned in all configured languages

  • If true, the question text is returned in all languages that it is configured in.
  • If false, the question text is returned in the user locale if available, else for the default locale.
  • If not passed, it behaves the same way as passing this parameter as false

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Set mfa kba configuration

This API sets answers to challenge questions. Any configured questions omitted from the request are removed from user KBA configuration.

Authorizations:
Personal Access Token
Request Body schema: application/json
Array
id
required
string

Question Id

answer
required
string

An answer for the KBA question

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Mfa method's test configuration

This API validates that the configuration is valid and will properly authenticate with the MFA provider identified by the method path parameter.

Authorizations:
Personal Access Token
path Parameters
method
required
string
Enum: "okta-verify" "duo-web"
Example: okta-verify

The name of the MFA method. The currently supported method names are 'okta-verify' and 'duo-web'.

Responses

Response samples

Content type
application/json
{
  • "state": "SUCCESS",
  • "error": null
}

Delete mfa method configuration

This API removes the configuration for the specified MFA method.

Authorizations:
Personal Access Token
path Parameters
method
required
string
Enum: "okta-verify" "duo-web"
Example: okta-verify

The name of the MFA method. The currently supported method names are 'okta-verify' and 'duo-web'.

Responses

Response samples

Content type
application/json
{
  • "mfaMethod": "okta-verify",
  • "enabled": true,
  • "host": "www.example.com",
  • "accessKey": "d******Y",
  • "identityAttribute": "email"
}

MFA Controller

This API used for multifactor authentication functionality belong to gov-multi-auth service. This controller allow you to verify authentication by specified method

Verifying authentication via okta method

This API Authenticates the user via Okta-Verify MFA method. Request requires a header called 'slpt-forwarding', and it must contain a remote IP Address of caller.

Authorizations:
Personal Access Token
Request Body schema: application/json
userId
required
string

User identifier for Verification request. The value of the user's attribute.

Responses

Request samples

Content type
application/json
{
  • "userId": "example@mail.com"
}

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "status": "SUCCESS",
  • "error": ""
}

Verifying authentication via duo method

This API Authenticates the user via Duo-Web MFA method.

Authorizations:
Personal Access Token
Request Body schema: application/json
userId
required
string

User id for Verification request.

signedResponse
required
string

User id for Verification request.

Responses

Request samples

Content type
application/json
{
  • "userId": "2c9180947f0ef465017f215cbcfd004b",
  • "signedResponse": "AUTH|d2lsbC5hbGJpbnxESTZNMFpHSThKQVRWTVpZN0M5VXwxNzAxMjUzMDg5|f1f5f8ced5b340f3d303b05d0efa0e43b6a8f970:APP|d2lsbC5hbGJpbnxESTZNMFpHSThKQVRWTVpZN0M5VXwxNzAxMjU2NjE5|cb44cf44353f5127edcae31b1da0355f87357db2"
}

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "status": "SUCCESS",
  • "error": ""
}

Polling mfa method by verificationpollrequest

This API poll the VerificationPollRequest for the specified MFA method.

Authorizations:
Personal Access Token
path Parameters
method
required
string
Enum: "okta-verify" "duo-web" "kba" "token" "rsa"
Example: okta-verify

The name of the MFA method. The currently supported method names are 'okta-verify', 'duo-web', 'kba','token', 'rsa'

Request Body schema: application/json
requestId
required
string

Verification request Id

Responses

Request samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9"
}

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "status": "PENDING",
  • "error": ""
}

Authenticate kba provided mfa method

This API Authenticate user in KBA MFA method.

Authorizations:
Personal Access Token
Request Body schema: application/json
Array
id
required
string

Question Id

answer
required
string

An answer for the KBA question

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "kbaAuthResponseItem": [
    ],
  • "status": "PENDING"
}

Authenticate token provided mfa method

This API Authenticate user in Token MFA method.

Authorizations:
Personal Access Token
Request Body schema: application/json
token
required
string

Token value

userAlias
required
string

User alias from table spt_identity field named 'name'

deliveryType
required
string
Enum: "SMS_PERSONAL" "VOICE_PERSONAL" "SMS_WORK" "VOICE_WORK" "EMAIL_WORK" "EMAIL_PERSONAL"

Token delivery type

Responses

Request samples

Content type
application/json
{
  • "token": "12345",
  • "userAlias": "will.albin",
  • "deliveryType": "EMAIL_WORK"
}

Response samples

Content type
application/json
{
  • "status": "PENDING"
}

Create and send user token

This API send token request.

Authorizations:
Personal Access Token
Request Body schema: application/json
userAlias
required
string

User alias from table spt_identity field named 'name'

deliveryType
required
string
Enum: "SMS_PERSONAL" "VOICE_PERSONAL" "SMS_WORK" "VOICE_WORK" "EMAIL_WORK" "EMAIL_PERSONAL"

Token delivery type

Responses

Request samples

Content type
application/json
{
  • "userAlias": "will.albin",
  • "deliveryType": "EMAIL_WORK"
}

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "status": "SUCCESS",
  • "errorMessage": ""
}

Non-Employee Lifecycle Management

Use this API to implement non-employee lifecycle management functionality. With this functionality in place, administrators can create non-employee records and configure them for use in their organizations. This allows organizations to provide secure access to non-employees and control that access.

The 'non-employee' term refers to any consultant, contractor, intern, or other user in an organization who is not a full-time permanent employee. Organizations can track non-employees' access and activity in Identity Security Cloud by creating and maintaining non-employee sources. Organizations can have a maximum of 50 non-employee sources.

By using SailPoint's Non-Employee Lifecycle Management functionality, you agree to the following:

  • SailPoint is not responsible for storing sensitive data. You may only add account attributes to non-employee identities that are necessary for business operations and are consistent with your contractual limitations on data that may be sent or stored in Identity Security Cloud.

  • You are responsible for regularly downloading your list of non-employee accounts for all the sources you create and storing this list of accounts in a managed location to maintain an authoritative system of record and backup data for these accounts.

To manage non-employees in Identity Security Cloud, administrators must create a non-employee source and add accounts to the source.

To create a non-employee source in Identity Security Cloud, administrators must use the Admin panel to go to Connections > Sources. They must then specify 'Non-Employee' in the 'Source Type' field. Refer to Creating a Non-Employee Source for more details about how to create non-employee sources.

To add accounts to a non-employee source in Identity Security Cloud, administrators can select the non-employee source and add the accounts. They can also use the 'Manage Non-Employees' widget on their user dashboards to reach the list of sources and then select the non-employee source they want to add the accounts to.

Administrators can either add accounts individually or in bulk. Each non-employee source can have a maximum of 20,000 accounts. To add accounts in bulk, they must select the 'Bulk Upload' option and upload a CSV file. Refer to Adding Accounts for more details about how to add accounts to non-employee sources.

Once administrators have created the non-employee source and added accounts to it, they can create identity profiles to generate identities for the non-employee accounts and manage the non-employee identities the same way they would any other identities.

Refer to Managing Non-Employee Sources and Accounts for more information about non-employee lifecycle management.

Create non-employee record

This request will create a non-employee record. Requires role context of idn:nesr:create

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json

Non-Employee record creation request body.

accountName
required
string

Requested identity account name.

firstName
required
string

Non-Employee's first name.

lastName
required
string

Non-Employee's last name.

email
required
string

Non-Employee's email.

phone
required
string

Non-Employee's phone.

manager
required
string

The account ID of a valid identity to serve as this non-employee's manager.

sourceId
required
string

Non-Employee's source id.

object

Additional attributes for a non-employee. Up to 10 custom attributes can be added.

startDate
required
string <date-time>

Non-Employee employment start date.

endDate
required
string <date-time>

Non-Employee employment end date.

Responses

Request samples

Content type
application/json
{
  • "accountName": "william.smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2020-03-24T00:00:00-05:00",
  • "endDate": "2021-03-25T00:00:00-05:00"
}

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "accountName": "Abby.Smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2019-08-23T18:52:59.162Z",
  • "endDate": "2020-08-23T18:52:59.162Z",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

List non-employee records

This gets a list of non-employee records. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:read, in which case they can get a list of all of the non-employees.
  2. The user is an account manager, in which case they can get a list of the non-employees that they manage.
Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

sorters
string <comma-separated>
Example: sorters=accountName,sourceId

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: id, accountName, sourceId, manager, firstName, lastName, email, phone, startDate, endDate, created, modified

filters
string
Example: filters=sourceId eq "2c91808568c529c60168cca6f90c1313"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

sourceId: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a non-employee record

This gets a non-employee record. Requires role context of idn:nesr:read

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Non-Employee record id (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "accountName": "Abby.Smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2019-08-23T18:52:59.162Z",
  • "endDate": "2020-08-23T18:52:59.162Z",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

Update non-employee record

This request will update a non-employee record. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:update, in which case they update all available fields.
  2. The user is owner of the source, in this case they can only update the end date.
Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Non-employee record id (UUID)

Request Body schema: application/json

Non-employee record creation request body. Attributes are restricted by user type. Owner of source can update end date. Organization admins can update all available fields.

accountName
required
string

Requested identity account name.

firstName
required
string

Non-Employee's first name.

lastName
required
string

Non-Employee's last name.

email
required
string

Non-Employee's email.

phone
required
string

Non-Employee's phone.

manager
required
string

The account ID of a valid identity to serve as this non-employee's manager.

sourceId
required
string

Non-Employee's source id.

object

Additional attributes for a non-employee. Up to 10 custom attributes can be added.

startDate
required
string <date-time>

Non-Employee employment start date.

endDate
required
string <date-time>

Non-Employee employment end date.

Responses

Request samples

Content type
application/json
{
  • "accountName": "william.smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2020-03-24T00:00:00-05:00",
  • "endDate": "2021-03-25T00:00:00-05:00"
}

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "accountName": "Abby.Smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2019-08-23T18:52:59.162Z",
  • "endDate": "2020-08-23T18:52:59.162Z",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

Patch non-employee record

This request will patch a non-employee record. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:update, in which case they update all available fields.
  2. The user is owner of the source, in this case they can only update the end date.
Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Non-employee record id (UUID)

Request Body schema: application/json-patch+json

A list of non-employee update operations according to the JSON Patch standard. Attributes are restricted by user type. Owner of source can update end date. Organization admins can update all available fields.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "accountName": "Abby.Smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2019-08-23T18:52:59.162Z",
  • "endDate": "2020-08-23T18:52:59.162Z",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

Delete non-employee record

This request will delete a non-employee record. Requires role context of idn:nesr:delete

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Non-Employee record id (UUID)

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Delete multiple non-employee records

This request will delete multiple non-employee records based on the non-employee ids provided. Requires role context of idn:nesr:delete

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json

Non-Employee bulk delete request body.

ids
required
Array of strings <uuid>

List of non-employee ids.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Create non-employee request

This request will create a non-employee request and notify the approver. Requires role context of idn:nesr:create or the user must own the source.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json

Non-Employee creation request body

accountName
required
string

Requested identity account name.

firstName
required
string

Non-Employee's first name.

lastName
required
string

Non-Employee's last name.

email
required
string

Non-Employee's email.

phone
required
string

Non-Employee's phone.

manager
required
string

The account ID of a valid identity to serve as this non-employee's manager.

sourceId
required
string

Non-Employee's source id.

object

Additional attributes for a non-employee. Up to 10 custom attributes can be added.

startDate
required
string <date-time>

Non-Employee employment start date.

endDate
required
string <date-time>

Non-Employee employment end date.

Responses

Request samples

Content type
application/json
{
  • "accountName": "william.smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "data": {
    },
  • "startDate": "2020-03-24T00:00:00-05:00",
  • "endDate": "2021-03-25T00:00:00-05:00"
}

Response samples

Content type
application/json
{
  • "id": "a0303682-5e4a-44f7-bdc2-6ce6112549c1",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "name": "Retail",
  • "description": "Source description",
  • "accountName": "william.smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "nonEmployeeSource": {
    },
  • "data": {
    },
  • "approvalItems": [
    ],
  • "approvalStatus": "APPROVED",
  • "comment": "approved",
  • "completionDate": "2020-03-24T11:11:41.139-05:00",
  • "startDate": "2020-03-24T00:00:00-05:00",
  • "endDate": "2021-03-25T00:00:00-05:00",
  • "modified": "2020-03-24T11:11:41.139-05:00",
  • "created": "2020-03-24T11:11:41.139-05:00"
}

List non-employee requests

This gets a list of non-employee requests. There are two contextual uses for the requested-for path parameter:

  1. The user has the role context of idn:nesr:read, in which case he or she may request a list non-employee requests assigned to a particular account manager by passing in that manager's id.
  2. The current user is an account manager, in which case "me" should be provided as the requested-for value. This will provide the user with a list of the non-employee requests in the source(s) he or she manages.
Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

requested-for
required
string
Example: requested-for=e136567de87e4d029e60b3c3c55db56d

The identity for whom the request was made. me indicates the current user.

sorters
string <comma-separated>
Example: sorters=created,approvalStatus

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: created, approvalStatus, firstName, lastName, email, phone, accountName, startDate, endDate

filters
string
Example: filters=sourceId eq "2c91808568c529c60168cca6f90c1313"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

sourceId: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a non-employee request

This gets a non-employee request. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:read, in this case the user can get the non-employee request for any user.
  2. The user must be the owner of the non-employee request.
Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ac110005-7156-1150-8171-5b292e3e0084

Non-Employee request id (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "a0303682-5e4a-44f7-bdc2-6ce6112549c1",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "name": "Retail",
  • "description": "Source description",
  • "accountName": "william.smith",
  • "firstName": "William",
  • "lastName": "Smith",
  • "email": "william.smith@example.com",
  • "phone": "5125555555",
  • "manager": "jane.doe",
  • "nonEmployeeSource": {
    },
  • "data": {
    },
  • "approvalItems": [
    ],
  • "approvalStatus": "APPROVED",
  • "comment": "approved",
  • "completionDate": "2020-03-24T11:11:41.139-05:00",
  • "startDate": "2020-03-24T00:00:00-05:00",
  • "endDate": "2021-03-25T00:00:00-05:00",
  • "modified": "2020-03-24T11:11:41.139-05:00",
  • "created": "2020-03-24T11:11:41.139-05:00"
}

Delete non-employee request

This request will delete a non-employee request. Requires role context of idn:nesr:delete

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string <uuid>
Example: ac110005-7156-1150-8171-5b292e3e0084

Non-Employee request id in the UUID format

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get summary of non-employee requests

This request will retrieve a summary of non-employee requests. There are two contextual uses for the requested-for path parameter:

  1. The user has the role context of idn:nesr:read, in which case he or she may request a summary of all non-employee approval requests assigned to a particular account manager by passing in that manager's id.
  2. The current user is an account manager, in which case "me" should be provided as the requested-for value. This will provide the user with a summary of the non-employee requests in the source(s) he or she manages.
Authorizations:
Personal Access TokenClient Credentials
path Parameters
requested-for
required
string <uuid (if user is Org Admin)>
Example: 2c91808280430dfb0180431a59440460

The identity (UUID) of the non-employee account manager for whom the summary is being retrieved. Use "me" instead to indicate the current user.

Responses

Response samples

Content type
application/json
{
  • "approved": 2,
  • "rejected": 2,
  • "pending": 2,
  • "nonEmployeeCount": 2
}

Create non-employee source

Create a non-employee source.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json

Non-Employee source creation request body.

name
required
string

Name of non-employee source.

description
required
string

Description of non-employee source.

required
object (NonEmployeeIdnUserRequest)
managementWorkgroup
string

The ID for the management workgroup that contains source sub-admins

Array of objects (NonEmployeeIdnUserRequest) <= 3 items

List of approvers.

Array of objects (NonEmployeeIdnUserRequest) <= 10 items

List of account managers.

Responses

Request samples

Content type
application/json
{
  • "name": "Retail",
  • "description": "Source description",
  • "owner": {
    },
  • "managementWorkgroup": "123299",
  • "approvers": [
    ],
  • "accountManagers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "a0303682-5e4a-44f7-bdc2-6ce6112549c1",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "name": "Retail",
  • "description": "Source description",
  • "approvers": [
    ],
  • "accountManagers": [
    ],
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "cloudExternalId": "99999"
}

List non-employee sources

Get a list of non-employee sources. There are two contextual uses for the requested-for path parameter:

  1. If the user has the role context of idn:nesr:read, he or she may request a list sources assigned to a particular account manager by passing in that manager's id.
  2. If the current user is an account manager, the user should provide 'me' as the requested-for value. Doing so provide the user with a list of the sources he or she owns.
Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

requested-for
string
Example: requested-for=me

Identity the request was made for. Use 'me' to indicate the current user.

non-employee-count
boolean
Default: false
Example: non-employee-count=true

Flag that determines whether the API will return a non-employee count associated with the source.

sorters
string <comma-separated>
Example: sorters=name,created

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, created, sourceId

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a non-employee source

This gets a non-employee source. There are two contextual uses for the requested-for path parameter:

  1. The user has the role context of idn:nesr:read, in which case he or she may request any source.
  2. The current user is an account manager, in which case the user can only request sources that they own.
Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: 2c91808b7c28b350017c2a2ec5790aa1

Source Id

Responses

Response samples

Content type
application/json
{
  • "id": "a0303682-5e4a-44f7-bdc2-6ce6112549c1",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "name": "Retail",
  • "description": "Source description",
  • "approvers": [
    ],
  • "accountManagers": [
    ],
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

Patch a non-employee source

patch a non-employee source. (partial update)
Patchable field: name, description, approvers, accountManagers Requires role context of idn:nesr:update.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Source Id

Request Body schema: application/json-patch+json

A list of non-employee source update operations according to the JSON Patch standard.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "a0303682-5e4a-44f7-bdc2-6ce6112549c1",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "name": "Retail",
  • "description": "Source description",
  • "approvers": [
    ],
  • "accountManagers": [
    ],
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z"
}

Delete non-employee source

This request will delete a non-employee source. Requires role context of idn:nesr:delete.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Source Id

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Exports non-employee records to csv

This requests a CSV download for all non-employees from a provided source. Requires role context of idn:nesr:read

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Source Id (UUID)

Responses

Response samples

Content type
text/csv
accountName,firstName,lastName,phone,email,manager,startDate,endDate
Jon.Smith, Jon, Smith, 555-555-5555, jon@jon.doe.nope.com, Jim Smith, 2020-04-05T08:00:00-10:00,2020-08-07T19:00:00-10:00
William.Chaffin, William, Chaffin, 555-555-5555, william@chaffins.nope.com, Bertram Chaffin, 2020-04-05T08:00:00-10:00,2020-08-07T19:00:00-10:00

Imports, or updates, non-employee records

This post will import, or update, Non-Employee records found in the CSV. Requires role context of idn:nesr:create

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Source Id (UUID)

Request Body schema: multipart/form-data
data
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808568c529c60168cca6f90cffff",
  • "sourceId": "2c91808568c529c60168cca6f90c1313",
  • "created": "2019-08-23T18:52:59.162Z",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "status": "PENDING"
}

Obtain the status of bulk upload on the source

The nonEmployeeBulkUploadStatus API returns the status of the newest bulk upload job for the specified source. Requires role context of idn:nesr:read

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Source ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "status": "PENDING"
}

Exports source schema template

This requests a download for the Source Schema Template for a provided source. Requires role context of idn:nesr:read

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Source Id (UUID)

Responses

Response samples

Content type
text/csv
accountName,firstName,lastName,phone,email,manager,startDate,endDate

Get list of non-employee approval requests

This gets a list of non-employee approval requests. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:read, in which case they can list the approvals for any approver.
  2. The user owns the requested approval.
Authorizations:
Personal Access TokenClient Credentials
query Parameters
requested-for
string
Example: requested-for=2c91808280430dfb0180431a59440460

The identity for whom the request was made. me indicates the current user.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=approvalStatus eq "Pending"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

approvalStatus: eq

sorters
string <comma-separated>
Example: sorters=created

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a non-employee approval item detail

Gets a non-employee approval item detail. There are two contextual uses for this endpoint:

  1. The user has the role context of idn:nesr:read, in which case they can get any approval.
  2. The user owns the requested approval.
Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Non-Employee approval item id (UUID)

query Parameters
include-detail
boolean
Example: include-detail=true

The object nonEmployeeRequest will not be included detail when set to false. Default value is true

Responses

Response samples

Content type
application/json
{
  • "id": "2c1e388b-1e55-4b0a-ab5c-897f1204159c",
  • "approver": {
    },
  • "accountName": "test.account",
  • "approvalStatus": "APPROVED",
  • "approvalOrder": 1,
  • "comment": "I approve",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "nonEmployeeRequest": {
    }
}

Approve a non-employee request

Approves a non-employee approval request and notifies the next approver. The current user must be the requested approver.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Non-Employee approval item id (UUID)

Request Body schema: application/json
comment
string <= 4000 characters

Comment on the approval item.

Responses

Request samples

Content type
application/json
{
  • "comment": "Approved by manager"
}

Response samples

Content type
application/json
{
  • "id": "2c1e388b-1e55-4b0a-ab5c-897f1204159c",
  • "approver": {
    },
  • "accountName": "test.account",
  • "approvalStatus": "APPROVED",
  • "approvalOrder": 1,
  • "comment": "I approve",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "nonEmployeeRequest": {
    }
}

Reject a non-employee request

This endpoint will reject an approval item request and notify user. The current user must be the requested approver.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: e136567de87e4d029e60b3c3c55db56d

Non-Employee approval item id (UUID)

Request Body schema: application/json
comment
required
string <= 4000 characters

Comment on the approval item.

Responses

Request samples

Content type
application/json
{
  • "comment": "approved"
}

Response samples

Content type
application/json
{
  • "id": "2c1e388b-1e55-4b0a-ab5c-897f1204159c",
  • "approver": {
    },
  • "accountName": "test.account",
  • "approvalStatus": "APPROVED",
  • "approvalOrder": 1,
  • "comment": "I approve",
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "nonEmployeeRequest": {
    }
}

Get summary of non-employee approval requests

This request will retrieve a summary of non-employee approval requests. There are two contextual uses for the requested-for path parameter:

  1. The user has the role context of idn:nesr:read, in which case he or she may request a summary of all non-employee approval requests assigned to a particular approver by passing in that approver's id.
  2. The current user is an approver, in which case "me" should be provided as the requested-for value. This will provide the approver with a summary of the approval items assigned to him or her.
Authorizations:
Personal Access TokenClient Credentials
path Parameters
requested-for
required
string
Example: 2c91808280430dfb0180431a59440460

The identity (UUID) of the approver for whom for whom the summary is being retrieved. Use "me" instead to indicate the current user.

Responses

Response samples

Content type
application/json
{
  • "approved": 2,
  • "pending": 2,
  • "rejected": 2
}

List schema attributes non-employee source

This API gets the list of schema attributes for the specified Non-Employee SourceId. There are 8 mandatory attributes added to each new Non-Employee Source automatically. Additionaly, user can add up to 10 custom attributes. This interface returns all the mandatory attributes followed by any custom attributes. At most, a total of 18 attributes will be returned. Requires role context of idn:nesr:read or the user must be an account manager of the source.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new schema attribute for non-employee source

This API creates a new schema attribute for Non-Employee Source. The schema technical name must be unique in the source. Attempts to create a schema attribute with an existing name will result in a "400.1.409 Reference conflict" response. At most, 10 custom attributes can be created per schema. Attempts to create more than 10 will result in a "400.1.4 Limit violation" response. Requires role context of idn:nesr:create

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Request Body schema: application/json
type
required
string

Type of the attribute. Only type 'TEXT' is supported for custom attributes.

label
required
string

Label displayed on the UI for this schema attribute.

technicalName
required
string

The technical name of the attribute. Must be unique per source.

helpText
string

help text displayed by UI.

placeholder
string

Hint text that fills UI box.

required
boolean

If true, the schema attribute is required for all non-employees in the source

Responses

Request samples

Content type
application/json
{
  • "type": "TEXT",
  • "label": "Account Name",
  • "technicalName": "account.name",
  • "helpText": "The unique identifier for the account",
  • "placeholder": "Enter a unique user name for this account.",
  • "required": true
}

Response samples

Content type
application/json
{
  • "id": "ac110005-7156-1150-8171-5b292e3e0084",
  • "system": true,
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "type": "TEXT",
  • "label": "Account Name",
  • "technicalName": "account.name",
  • "helpText": "The unique identifier for the account",
  • "placeholder": "Enter a unique user name for this account.",
  • "required": true
}

Delete all custom schema attributes for non-employee source

This end-point deletes all custom schema attributes for a non-employee source. Requires role context of idn:nesr:delete

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get schema attribute non-employee source

This API gets a schema attribute by Id for the specified Non-Employee SourceId. Requires role context of idn:nesr:read or the user must be an account manager of the source.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
attributeId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Schema Attribute Id (UUID)

sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Responses

Response samples

Content type
application/json
{
  • "id": "ac110005-7156-1150-8171-5b292e3e0084",
  • "system": true,
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "type": "TEXT",
  • "label": "Account Name",
  • "technicalName": "account.name",
  • "helpText": "The unique identifier for the account",
  • "placeholder": "Enter a unique user name for this account.",
  • "required": true
}

Patch a schema attribute for non-employee source

This end-point patches a specific schema attribute for a non-employee SourceId. Requires role context of idn:nesr:update

Authorizations:
Personal Access TokenClient Credentials
path Parameters
attributeId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Schema Attribute Id (UUID)

sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Request Body schema: application/json-patch+json

A list of schema attribute update operations according to the JSON Patch standard. The following properties are allowed for update ':' 'label', 'helpText', 'placeholder', 'required'.

Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "ac110005-7156-1150-8171-5b292e3e0084",
  • "system": true,
  • "modified": "2019-08-23T18:52:59.162Z",
  • "created": "2019-08-23T18:40:35.772Z",
  • "type": "TEXT",
  • "label": "Account Name",
  • "technicalName": "account.name",
  • "helpText": "The unique identifier for the account",
  • "placeholder": "Enter a unique user name for this account.",
  • "required": true
}

Delete a schema attribute for non-employee source

This end-point deletes a specific schema attribute for a non-employee source. Requires role context of idn:nesr:delete

Authorizations:
Personal Access TokenClient Credentials
path Parameters
attributeId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Schema Attribute Id (UUID)

sourceId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Source id

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

OAuth Clients

Use this API to implement OAuth client functionality.
With this functionality in place, users with the appropriate security scopes can create and configure OAuth clients to use as a way to obtain authorization to use the Identity Security Cloud REST API. Refer to Authentication for more information about OAuth and how it works with the Identity Security Cloud REST API.

List oauth clients

This gets a list of OAuth clients.

Authorizations:
Personal Access Token
query Parameters
filters
string
Example: filters=lastUsed le 2023-02-05T10:59:27.214Z

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

lastUsed: le, isnull

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create oauth client

This creates an OAuth client.

Authorizations:
Personal Access Token
Request Body schema: application/json
businessName
string or null

The name of the business the API Client should belong to

homepageUrl
string or null

The homepage URL associated with the owner of the API Client

name
required
string or null

A human-readable name for the API Client

description
required
string or null

A description of the API Client

accessTokenValiditySeconds
required
integer <int32>

The number of seconds an access token generated for this API Client is valid for

refreshTokenValiditySeconds
integer <int32>

The number of seconds a refresh token generated for this API Client is valid for

redirectUris
Array of strings or null

A list of the approved redirect URIs. Provide one or more URIs when assigning the AUTHORIZATION_CODE grant type to a new OAuth Client.

grantTypes
required
Array of strings or null (GrantType)
Enum: "CLIENT_CREDENTIALS" "AUTHORIZATION_CODE" "REFRESH_TOKEN"

A list of OAuth 2.0 grant types this API Client can be used with

accessType
required
string (AccessType)
Enum: "ONLINE" "OFFLINE"

Access type of API Client indicating online or offline use

type
string (ClientType)
Enum: "CONFIDENTIAL" "PUBLIC"

Type of an API Client indicating public or confidentials use

internal
boolean

An indicator of whether the API Client can be used for requests internal within the product.

enabled
required
boolean

An indicator of whether the API Client is enabled for use

strongAuthSupported
boolean

An indicator of whether the API Client supports strong authentication

claimsSupported
boolean

An indicator of whether the API Client supports the serialization of SAML claims when used with the authorization_code flow

scope
Array of strings or null

Scopes of the API Client. If no scope is specified, the client will be created with the default scope "sp:scopes:all". This means the API Client will have all the rights of the owner who created it.

Responses

Request samples

Content type
application/json
{
  • "businessName": "Acme-Solar",
  • "homepageUrl": "http://localhost:12345",
  • "name": "Demo API Client",
  • "description": "An API client used for the authorization_code, refresh_token, and client_credentials flows",
  • "accessTokenValiditySeconds": 750,
  • "refreshTokenValiditySeconds": 86400,
  • "redirectUris": [],
  • "grantTypes": [
    ],
  • "accessType": "OFFLINE",
  • "type": "CONFIDENTIAL",
  • "internal": false,
  • "enabled": true,
  • "strongAuthSupported": false,
  • "claimsSupported": false,
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "secret": "5c32dd9b21adb51c77794d46e71de117a1d0ddb36a7ff941fa28014ab7de2cf3",
  • "businessName": "Acme-Solar",
  • "homepageUrl": "http://localhost:12345",
  • "name": "Demo API Client",
  • "description": "An API client used for the authorization_code, refresh_token, and client_credentials flows",
  • "accessTokenValiditySeconds": 750,
  • "refreshTokenValiditySeconds": 86400,
  • "redirectUris": [],
  • "grantTypes": [
    ],
  • "accessType": "OFFLINE",
  • "type": "CONFIDENTIAL",
  • "internal": false,
  • "enabled": true,
  • "strongAuthSupported": false,
  • "claimsSupported": false,
  • "created": "2017-07-11T18:45:37.098Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "scope": [
    ]
}

Get oauth client

This gets details of an OAuth client.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The OAuth client id

Responses

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "businessName": "Acme-Solar",
  • "homepageUrl": "http://localhost:12345",
  • "name": "Demo API Client",
  • "description": "An API client used for the authorization_code, refresh_token, and client_credentials flows",
  • "accessTokenValiditySeconds": 750,
  • "refreshTokenValiditySeconds": 86400,
  • "redirectUris": [],
  • "grantTypes": [
    ],
  • "accessType": "OFFLINE",
  • "type": "CONFIDENTIAL",
  • "internal": false,
  • "enabled": true,
  • "strongAuthSupported": false,
  • "claimsSupported": false,
  • "created": "2017-07-11T18:45:37.098Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "secret": "string",
  • "metadata": "string",
  • "lastUsed": "2017-07-11T18:45:37.098Z",
  • "scope": [
    ]
}

Delete oauth client

This deletes an OAuth client.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The OAuth client id

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Patch oauth client

This performs a targeted update to the field(s) of an OAuth client.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The OAuth client id

Request Body schema: application/json-patch+json

A list of OAuth client update operations according to the JSON Patch standard.

The following fields are patchable:

  • tenant
  • businessName
  • homepageUrl
  • name
  • description
  • accessTokenValiditySeconds
  • refreshTokenValiditySeconds
  • redirectUris
  • grantTypes
  • accessType
  • enabled
  • strongAuthSupported
  • claimsSupported
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c9180835d2e5168015d32f890ca1581",
  • "businessName": "Acme-Solar",
  • "homepageUrl": "http://localhost:12345",
  • "name": "Demo API Client",
  • "description": "An API client used for the authorization_code, refresh_token, and client_credentials flows",
  • "accessTokenValiditySeconds": 750,
  • "refreshTokenValiditySeconds": 86400,
  • "redirectUris": [],
  • "grantTypes": [
    ],
  • "accessType": "OFFLINE",
  • "type": "CONFIDENTIAL",
  • "internal": false,
  • "enabled": true,
  • "strongAuthSupported": false,
  • "claimsSupported": false,
  • "created": "2017-07-11T18:45:37.098Z",
  • "modified": "2018-06-25T20:22:28.104Z",
  • "secret": "string",
  • "metadata": "string",
  • "lastUsed": "2017-07-11T18:45:37.098Z",
  • "scope": [
    ]
}

Password Configuration

Use this API to implement organization password configuration functionality. With this functionality in place, organization administrators can create organization-specific password configurations.

These configurations include details like custom password instructions, as well as digit token length and duration.

Refer to Configuring User Authentication for Password Resets for more information about organization password configuration functionality.

Get password org config

This API returns the password org config . Requires ORG_ADMIN, API role or authorization scope of 'idn:password-org-config:read'

Authorizations:
Personal Access TokenClient Credentials

Responses

Response samples

Content type
application/json
{
  • "customInstructionsEnabled": true,
  • "digitTokenDurationMinutes": 9,
  • "digitTokenEnabled": false,
  • "digitTokenLength": 6
}

Update password org config

This API updates the password org config for specified fields. Other fields will keep original value. You must set the customInstructionsEnabled field to "true" to be able to use custom password instructions. Requires ORG_ADMIN, API role or authorization scope of 'idn:password-org-config:write'

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
customInstructionsEnabled
boolean
Default: false

Indicator whether custom password instructions feature is enabled. The default value is false.

digitTokenEnabled
boolean
Default: false

Indicator whether "digit token" feature is enabled. The default value is false.

digitTokenDurationMinutes
integer <int32> [ 1 .. 60 ]
Default: 5

The duration of "digit token" in minutes. The default value is 5.

digitTokenLength
integer <int32> [ 6 .. 18 ]
Default: 6

The length of "digit token". The default value is 6.

Responses

Request samples

Content type
application/json
{
  • "digitTokenEnabled": true,
  • "digitTokenDurationMinutes": 12
}

Response samples

Content type
application/json
{
  • "customInstructionsEnabled": true,
  • "digitTokenDurationMinutes": 12,
  • "digitTokenEnabled": true,
  • "digitTokenLength": 6
}

Create password org config

This API creates the password org config. Unspecified fields will use default value. To be able to use the custom password instructions, you must set the customInstructionsEnabled field to "true". Requires ORG_ADMIN, API role or authorization scope of 'idn:password-org-config:write'

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
customInstructionsEnabled
boolean
Default: false

Indicator whether custom password instructions feature is enabled. The default value is false.

digitTokenEnabled
boolean
Default: false

Indicator whether "digit token" feature is enabled. The default value is false.

digitTokenDurationMinutes
integer <int32> [ 1 .. 60 ]
Default: 5

The duration of "digit token" in minutes. The default value is 5.

digitTokenLength
integer <int32> [ 6 .. 18 ]
Default: 6

The length of "digit token". The default value is 6.

Responses

Request samples

Content type
application/json
{
  • "customInstructionsEnabled": true,
  • "digitTokenEnabled": true,
  • "digitTokenDurationMinutes": 12,
  • "digitTokenLength": 9
}

Response samples

Content type
application/json
{
  • "customInstructionsEnabled": true,
  • "digitTokenDurationMinutes": 9,
  • "digitTokenEnabled": true,
  • "digitTokenLength": 12
}

Password Dictionary

Use this API to implement password dictionary functionality.
With this functionality in place, administrators can create password dictionaries to prevent users from using certain words or characters in their passwords.

A password dictionary is a list of words or characters that users are prevented from including in their passwords. This can help protect users from themselves and force them to create passwords that are not easy to break.

A password dictionary must meet the following requirements to for the API to handle them correctly:

  • It must be in .txt format.

  • All characters must be UTF-8 characters.

  • Each line must contain a single word or character with no spaces or whitespace characters.

  • It must contain at least one line other than the locale string.

  • Each line must not exceed 128 characters.

  • The file must not exceed 2500 lines.

Administrators should also consider the following when they create their dictionaries:

  • Lines starting with a # represent comments.

  • All words in the password dictionary are case-insensitive. For example, adding the word "password" to the dictionary also disallows the following: PASSWORD, Password, and PassWord.

  • The dictionary uses substring matching. For example, adding the word "spring" to the dictionary also disallows the following: Spring124, 345SprinG, and 8spring. Users can then select 'Change Password' to update their passwords.

Administrators must do the following to create a password dictionary:

  • Create the text file that will contain the prohibited password values.

  • If the dictionary is not in English, they must add a locale string to the top line: locale:languageCode_countryCode

The languageCode value refers to the language's 2-letter ISO 639-1 code. The countryCode value refers to the country's 2-letter ISO 3166-1 code.

Refer to this list https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html to see all the available ISO 639-1 language codes and ISO 3166-1 country codes.

  • Upload the .txt file to Identity Security Cloud with Update Password Dictionary. Uploading a new file always overwrites the previous dictionary file.

Administrators can then specify which password policies check new passwords against the password dictionary by doing the following: In the Admin panel, they can use the Password Mgmt dropdown menu to select Policies, select the policy, and select the 'Prevent use of words in this site's password dictionary' checkbox beside it.

Refer to Configuring Advanced Password Management Options for more information about password dictionaries.

Get password dictionary

This gets password dictionary for the organization. The password dictionary file can contain lines that are:

  1. comment lines - the first character is '#', can be 128 Unicode codepoints in length, and are ignored during processing
  2. empty lines
  3. locale line - the first line that starts with "locale=" is considered to be locale line, the rest are treated as normal content lines
  4. line containing the password dictionary word - it must start with non-whitespace character and only non-whitespace characters are allowed; maximum length of the line is 128 Unicode codepoints

Password dictionary file may not contain more than 2,500 lines (not counting whitespace lines, comment lines and locale line). Password dict file must contain UTF-8 characters only.

Sample password text file


# Password dictionary small test file

locale=en_US

# Password dictionary prohibited words

qwerty
abcd
aaaaa
password
qazxsws
Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Update password dictionary

This updates password dictionary for the organization. The password dictionary file can contain lines that are:

  1. comment lines - the first character is '#', can be 128 Unicode codepoints in length, and are ignored during processing
  2. empty lines
  3. locale line - the first line that starts with "locale=" is considered to be locale line, the rest are treated as normal content lines
  4. line containing the password dictionary word - it must start with non-whitespace character and only non-whitespace characters are allowed; maximum length of the line is 128 Unicode codepoints

Password dictionary file may not contain more than 2,500 lines (not counting whitespace lines, comment lines and locale line). Password dict file must contain UTF-8 characters only.

Sample password text file


# Password dictionary small test file

locale=en_US

# Password dictionary prohibited words

qwerty
abcd
aaaaa
password
qazxsws
Authorizations:
Personal Access Token
Request Body schema: multipart/form-data

The password dictionary file to be uploaded.

file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Password Management

Use this API to implement password management functionality.
With this functionality in place, users can manage their identity passwords for all their applications.

In Identity Security Cloud, users can select their names in the upper right corner of the page and use the drop-down menu to select Password Manager. Password Manager lists the user's identity's applications, possibly grouped to share passwords. Users can then select 'Change Password' to update their passwords.

Grouping passwords allows users to update their passwords more broadly, rather than requiring them to update each password individually. Password Manager may list the applications and sources in the following groups:

  • Password Group: This refers to a group of applications that share a password. For example, a user can use the same password for Google Drive, Google Mail, and YouTube. Updating the password for the password group updates the password for all its included applications.

  • Multi-Application Source: This refers to a source with multiple applications that share a password. For example, a user can have a source, G Suite, that includes the Google Calendar, Google Drive, and Google Mail applications. Updating the password for the multi-application source updates the password for all its included applications.

  • Applications: These are applications that do not share passwords with other applications.

An organization may require some authentication for users to update their passwords. Users may be required to answer security questions or use a third-party authenticator before they can confirm their updates.

Refer to Managing Passwords for more information about password management.

Query password info

This API is used to query password related information.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
userName
string

The login name of the user

sourceName
string

The display name of the source

Responses

Request samples

Content type
application/json
{
  • "userName": "Abby.Smith",
  • "sourceName": "My-AD"
}

Response samples

Content type
application/json
{
  • "identityId": "2c918085744fec4301746f9a5bce4605",
  • "sourceId": "2c918083746f642c01746f990884012a",
  • "publicKeyId": "N2M1OTJiMGEtMDJlZS00ZWU3LTkyYTEtNjA5YmI5NWE3ZWVh",
  • "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuGFkWi2J75TztpbaPKd36bJnIB3J8gZ6UcoS9oSDYsqBzPpTsfZXYaEf4Y4BKGgJIXmE/lwhwuj7mU1itdZ2qTSNFtnXA8Fn75c3UUkk+h+wdZbkuSmqlsJo3R1OnJkwkJggcAy9Jvk9jlcrNLWorpQ1w9raUvxtvfgkSdq153KxotenQ1HciSyZ0nA/Kw0UaucLnho8xdRowZs11afXGXA9IT9H6D8T6zUdtSxm0nAyH+mluma5LdTfaM50W3l/L8q56Vrqmx2pZIiwdx/0+g3Y++jV70zom0ZBkC1MmSoLMrQYG5OICNjr72f78B2PaGXfarQHqARLjKpMVt9YIQIDAQAB",
  • "accounts": [
    ],
  • "policies": [
    ]
}

Set identity's password

This API is used to set a password for an identity.

An identity can change their own password (as well as any of their accounts' passwords) if they use a token generated by their ISC user, such as a personal access token or "authorization_code" derived OAuth token.

Note: If you want to set an identity's source account password, you must enable PASSWORD as one of the source's features. You can use the PATCH Source endpoint to add the PASSWORD feature.

To generate the encryptedPassword (RSA encrypted using publicKey) for the request body, run the following command:

echo -n "myPassword" | openssl pkeyutl -encrypt -inkey public_key.pem -pubin | base64

In this example, myPassword is the plain text password being set and encrypted, and public_key.pem is the path to the public key file. You can retrieve the required publicKey, along with other information like identityId, sourceId, publicKeyId, accounts, and policies, using the Query Password Info endpoint.

To successfully run this command, you must have OpenSSL installed on your machine. If OpenSSL is unavailable, consider using the Virtual Appliance (VA), which has OpenSSL pre-installed and configured.

If you are using a Windows machine, refer to this guide for instructions on installing OpenSSL.

You can then use Get Password Change Request Status to check the password change request status. To do so, you must provide the requestId from your earlier request to set the password.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
identityId
string

The identity ID that requested the password change

encryptedPassword
string

The RSA encrypted password

publicKeyId
string

The encryption key ID

accountId
string

Account ID of the account This is specified per account schema in the source configuration. It is used to distinguish accounts. More info can be found here https://community.sailpoint.com/t5/IdentityNow-Connectors/How-do-I-designate-an-account-attribute-as-the-Account-ID-for-a/ta-p/80350

sourceId
string

The ID of the source for which identity is requesting the password change

Responses

Request samples

Content type
application/json
{
  • "identityId": "8a807d4c73c545510173c545f0a002ff",
  • "encryptedPassword": "XzN+YwKgr2C+InkMYFMBG3UtjMEw5ZIql/XFlXo8cJNeslmkplx6vn4kd4/43IF9STBk5RnzR6XmjpEO+FwHDoiBwYZAkAZK/Iswxk4OdybG6Y4MStJCOCiK8osKr35IMMSV/mbO4wAeltoCk7daTWzTGLiI6UaT5tf+F2EgdjJZ7YqM8W8r7aUWsm3p2Xt01Y46ZRx0QaM91QruiIx2rECFT2pUO0wr+7oQ77jypATyGWRtADsu3YcvCk/6U5MqCnXMzKBcRas7NnZdSL/d5H1GglVGz3VLPMaivG4/oL4chOMmFCRl/zVsGxZ9RhN8rxsRGFFKn+rhExTi+bax3A==",
  • "publicKeyId": "YWQ2NjQ4MTItZjY0NC00MWExLWFjMjktOGNmMzU3Y2VlNjk2",
  • "accountId": "CN=Abby Smith,OU=Austin,OU=Americas,OU=Demo,DC=seri,DC=acme,DC=com",
  • "sourceId": "8a807d4c73c545510173c545d4b60246"
}

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "state": "IN_PROGRESS"
}

Get password change request status

This API returns the status of a password change request.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 089899f13a8f4da7824996191587bab9

Password change request ID

Responses

Response samples

Content type
application/json
{
  • "requestId": "089899f13a8f4da7824996191587bab9",
  • "state": "IN_PROGRESS",
  • "errors": [
    ],
  • "sourceIds": [
    ]
}

Password Policies

Use these APIs to implement password policies functionality. These APIs allow you to define the policy parameters for choosing passwords.

IdentityNow comes with a default policy that you can modify to define the password requirements your users must meet to log in to IdentityNow, such as requiring a minimum password length, including special characters, and disallowing certain patterns. If you have licensed Password Management, you can create additional password policies beyond the default one to manage passwords for supported sources in your org.

In the Identity Security Cloud Admin panel, administrators can use the Password Mgmt dropdown menu to select Sync Groups. Refer to Managing Password Policies for more information about password policies.

Get password policy by id

This API returns the password policy for the specified ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: ff808081838d9e9d01838da6a03e0005

The ID of password policy to retrieve.

Responses

Response samples

Content type
application/json
{
  • "description": "Default Password Policy",
  • "id": "2c91808e7d976f3b017d9f5ceae440c8",
  • "name": "Example PP",
  • "dateCreated": 1639056206564,
  • "lastUpdated": 1662385430753,
  • "firstExpirationReminder": 90,
  • "accountIdMinWordLength": 3,
  • "accountNameMinWordLength": 3,
  • "maxLength": 0,
  • "maxRepeatedChars": 4,
  • "minAlpha": 1,
  • "minCharacterTypes": -1,
  • "minLength": 8,
  • "minLower": 0,
  • "minNumeric": 1,
  • "minSpecial": 0,
  • "minUpper": 0,
  • "passwordExpiration": 90,
  • "defaultPolicy": true,
  • "enablePasswdExpiration": false,
  • "requireStrongAuthn": false,
  • "requireStrongAuthOffNetwork": false,
  • "requireStrongAuthUntrustedGeographies": false,
  • "useAccountAttributes": false,
  • "useDictionary": false,
  • "useIdentityAttributes": false,
  • "validateAgainstAccountId": true,
  • "validateAgainstAccountName": true,
  • "sourceIds": [
    ]
}

Update password policy by id

This API updates the specified password policy.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ff808081838d9e9d01838da6a03e0007

The ID of password policy to update.

Request Body schema: application/json
id
string

The password policy Id.

description
string or null

Description for current password policy.

name
string

The name of the password policy.

dateCreated
string <date-time>

Date the Password Policy was created.

lastUpdated
string or null <date-time>

Date the Password Policy was updated.

firstExpirationReminder
integer <int64>

The number of days before expiration remaninder.

accountIdMinWordLength
integer <int64>

The minimun length of account Id. By default is equals to -1.

accountNameMinWordLength
integer <int64>

The minimun length of account name. By default is equals to -1.

minAlpha
integer <int64>

Maximum alpha. By default is equals to 0.

minCharacterTypes
integer <int64>

MinCharacterTypes. By default is equals to -1.

maxLength
integer <int64>

Maximum length of the password.

minLength
integer <int64>

Minimum length of the password. By default is equals to 0.

maxRepeatedChars
integer <int64>

Maximum repetition of the same character in the password. By default is equals to -1.

minLower
integer <int64>

Minimum amount of lower case character in the password. By default is equals to 0.

minNumeric
integer <int64>

Minimum amount of numeric characters in the password. By default is equals to 0.

minSpecial
integer <int64>

Minimum amount of special symbols in the password. By default is equals to 0.

minUpper
integer <int64>

Minimum amount of upper case symbols in the password. By default is equals to 0.

passwordExpiration
integer <int64>

Number of days before current password expires. By default is equals to 90.

defaultPolicy
boolean
Default: false

Defines whether this policy is default or not. Default policy is created automatically when an org is setup. This field is false by default.

enablePasswdExpiration
boolean
Default: false

Defines whether this policy is enabled to expire or not. This field is false by default.

requireStrongAuthn
boolean
Default: false

Defines whether this policy require strong Auth or not. This field is false by default.

requireStrongAuthOffNetwork
boolean
Default: false

Defines whether this policy require strong Auth of network or not. This field is false by default.

requireStrongAuthUntrustedGeographies
boolean
Default: false

Defines whether this policy require strong Auth for untrusted geographies. This field is false by default.

useAccountAttributes
boolean
Default: false

Defines whether this policy uses account attributes or not. This field is false by default.

useDictionary
boolean
Default: false

Defines whether this policy uses dictionary or not. This field is false by default.

useIdentityAttributes
boolean
Default: false

Defines whether this policy uses identity attributes or not. This field is false by default.

validateAgainstAccountId
boolean
Default: false

Defines whether this policy validate against account id or not. This field is false by default.

validateAgainstAccountName
boolean
Default: false

Defines whether this policy validate against account name or not. This field is false by default.

created
string or null
modified
string or null
sourceIds
Array of strings

List of sources IDs managed by this password policy.

Responses

Request samples

Content type
application/json
{
  • "description": "Password Policy after update.",
  • "id": "2c91808e7d976f3b017d9f5ceae440c8",
  • "name": "Improved Password Policy",
  • "dateCreated": 1639056206564,
  • "lastUpdated": 1662385430753,
  • "firstExpirationReminder": 90,
  • "accountIdMinWordLength": 3,
  • "accountNameMinWordLength": 3,
  • "maxLength": 0,
  • "maxRepeatedChars": 4,
  • "minAlpha": 1,
  • "minCharacterTypes": -1,
  • "minLength": 8,
  • "minLower": 0,
  • "minNumeric": 1,
  • "minSpecial": 0,
  • "minUpper": 0,
  • "passwordExpiration": 90,
  • "defaultPolicy": false,
  • "enablePasswdExpiration": false,
  • "requireStrongAuthn": false,
  • "requireStrongAuthOffNetwork": false,
  • "requireStrongAuthUntrustedGeographies": false,
  • "useAccountAttributes": false,
  • "useDictionary": false,
  • "useIdentityAttributes": false,
  • "validateAgainstAccountId": true,
  • "validateAgainstAccountName": true,
  • "sourceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "Password Policy after update.",
  • "id": "2c91808e7d976f3b017d9f5ceae440c8",
  • "name": "Improved Password Policy",
  • "dateCreated": 1639056206564,
  • "lastUpdated": 1662385430753,
  • "firstExpirationReminder": 90,
  • "accountIdMinWordLength": 3,
  • "accountNameMinWordLength": 3,
  • "maxLength": 0,
  • "maxRepeatedChars": 4,
  • "minAlpha": 1,
  • "minCharacterTypes": -1,
  • "minLength": 8,
  • "minLower": 0,
  • "minNumeric": 1,
  • "minSpecial": 0,
  • "minUpper": 0,
  • "passwordExpiration": 90,
  • "defaultPolicy": false,
  • "enablePasswdExpiration": false,
  • "requireStrongAuthn": false,
  • "requireStrongAuthOffNetwork": false,
  • "requireStrongAuthUntrustedGeographies": false,
  • "useAccountAttributes": false,
  • "useDictionary": false,
  • "useIdentityAttributes": false,
  • "validateAgainstAccountId": true,
  • "validateAgainstAccountName": true,
  • "sourceIds": [
    ]
}

Delete password policy by id

This API deletes the specified password policy.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ff808081838d9e9d01838da6a03e0002

The ID of password policy to delete.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Create password policy

This API creates the specified password policy.

Authorizations:
Personal Access Token
Request Body schema: application/json
id
string

The password policy Id.

description
string or null

Description for current password policy.

name
string

The name of the password policy.

dateCreated
string <date-time>

Date the Password Policy was created.

lastUpdated
string or null <date-time>

Date the Password Policy was updated.

firstExpirationReminder
integer <int64>

The number of days before expiration remaninder.

accountIdMinWordLength
integer <int64>

The minimun length of account Id. By default is equals to -1.

accountNameMinWordLength
integer <int64>

The minimun length of account name. By default is equals to -1.

minAlpha
integer <int64>

Maximum alpha. By default is equals to 0.

minCharacterTypes
integer <int64>

MinCharacterTypes. By default is equals to -1.

maxLength
integer <int64>

Maximum length of the password.

minLength
integer <int64>

Minimum length of the password. By default is equals to 0.

maxRepeatedChars
integer <int64>

Maximum repetition of the same character in the password. By default is equals to -1.

minLower
integer <int64>

Minimum amount of lower case character in the password. By default is equals to 0.

minNumeric
integer <int64>

Minimum amount of numeric characters in the password. By default is equals to 0.

minSpecial
integer <int64>

Minimum amount of special symbols in the password. By default is equals to 0.

minUpper
integer <int64>

Minimum amount of upper case symbols in the password. By default is equals to 0.

passwordExpiration
integer <int64>

Number of days before current password expires. By default is equals to 90.

defaultPolicy
boolean
Default: false

Defines whether this policy is default or not. Default policy is created automatically when an org is setup. This field is false by default.

enablePasswdExpiration
boolean
Default: false

Defines whether this policy is enabled to expire or not. This field is false by default.

requireStrongAuthn
boolean
Default: false

Defines whether this policy require strong Auth or not. This field is false by default.

requireStrongAuthOffNetwork
boolean
Default: false

Defines whether this policy require strong Auth of network or not. This field is false by default.

requireStrongAuthUntrustedGeographies
boolean
Default: false

Defines whether this policy require strong Auth for untrusted geographies. This field is false by default.

useAccountAttributes
boolean
Default: false

Defines whether this policy uses account attributes or not. This field is false by default.

useDictionary
boolean
Default: false

Defines whether this policy uses dictionary or not. This field is false by default.

useIdentityAttributes
boolean
Default: false

Defines whether this policy uses identity attributes or not. This field is false by default.

validateAgainstAccountId
boolean
Default: false

Defines whether this policy validate against account id or not. This field is false by default.

validateAgainstAccountName
boolean
Default: false

Defines whether this policy validate against account name or not. This field is false by default.

created
string or null
modified
string or null
sourceIds
Array of strings

List of sources IDs managed by this password policy.

Responses

Request samples

Content type
application/json
{
  • "description": "New Password Policy with high requirements to password complexity.",
  • "id": null,
  • "name": "High security Password Policy",
  • "dateCreated": 1639056206564,
  • "lastUpdated": 1662385430753,
  • "firstExpirationReminder": 90,
  • "accountIdMinWordLength": 3,
  • "accountNameMinWordLength": 3,
  • "maxLength": 0,
  • "maxRepeatedChars": 4,
  • "minAlpha": 1,
  • "minCharacterTypes": -1,
  • "minLength": 8,
  • "minLower": 0,
  • "minNumeric": 1,
  • "minSpecial": 0,
  • "minUpper": 0,
  • "passwordExpiration": 90,
  • "defaultPolicy": false,
  • "enablePasswdExpiration": false,
  • "requireStrongAuthn": false,
  • "requireStrongAuthOffNetwork": false,
  • "requireStrongAuthUntrustedGeographies": false,
  • "useAccountAttributes": false,
  • "useDictionary": false,
  • "useIdentityAttributes": false,
  • "validateAgainstAccountId": true,
  • "validateAgainstAccountName": true,
  • "sourceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "2c91808e7d976f3b017d9f5ceae440c8",
  • "description": "Information about the Password Policy",
  • "name": "PasswordPolicy Example",
  • "dateCreated": 1639056206564,
  • "lastUpdated": 1939056206564,
  • "firstExpirationReminder": 45,
  • "accountIdMinWordLength": 4,
  • "accountNameMinWordLength": 6,
  • "minAlpha": 5,
  • "minCharacterTypes": 5,
  • "maxLength": 25,
  • "minLength": 8,
  • "maxRepeatedChars": 3,
  • "minLower": 8,
  • "minNumeric": 8,
  • "minSpecial": 8,
  • "minUpper": 8,
  • "passwordExpiration": 8,
  • "defaultPolicy": true,
  • "enablePasswdExpiration": true,
  • "requireStrongAuthn": true,
  • "requireStrongAuthOffNetwork": true,
  • "requireStrongAuthUntrustedGeographies": true,
  • "useAccountAttributes": false,
  • "useDictionary": false,
  • "useIdentityAttributes": false,
  • "validateAgainstAccountId": false,
  • "validateAgainstAccountName": true,
  • "created": "string",
  • "modified": "string",
  • "sourceIds": [
    ]
}

List password policies

This gets list of all Password Policies. Requires role of ORG_ADMIN

Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Password Sync Groups

Use this API to implement password sync group functionality. With this functionality in place, administrators can group sources into password sync groups so that all their applications share the same password. This allows users to update the password for all the applications in a sync group if they want, rather than updating each password individually.

A password sync group is a group of applications that shares a password. Administrators create these groups by grouping the applications' sources. For example, an administrator can group the ActiveDirectory, GitHub, and G Suite sources together so that all those sources' applications can also be grouped to share a password. A user can then update his or her password for ActiveDirectory, GitHub, Gmail, Google Drive, and Google Calendar all at once, rather then updating each one individually.

The following are required for administrators to create a password sync group in Identity Security Cloud:

  • At least two direct connect sources connected to Identity Security Cloud and configured for Password Management.

  • Each authentication source in a sync group must have at least one application. Refer to Adding and Resetting Application Passwords for more information about adding applications to sources.

  • At least one password policy. Refer to Managing Password Policies for more information about password policies.

In the Admin panel in Identity Security Cloud, administrators can use the Password Mgmt dropdown menu to select Sync Groups. To create a sync group, administrators must provide a name, choose a password policy to be enforced across the sources in the sync group, and select the sources to include in the sync group.

Administrators can also delete sync groups in Identity Security Cloud, but they should know the following before they do:

  • Passwords related to the associated sources will become independent, so changing one will not change the others anymore.

  • Passwords for the sources' connected applications will also become independent.

  • Password policies assigned to the sync group are then assigned directly to the associated sources. To change the password policy for a source, administrators must edit it directly.

Once the password sync group has been created, users can update the password for the group in Password Manager.

Refer to Managing Password Sync Groups for more information about password sync groups.

Get password sync group list

This API returns a list of password sync groups.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create password sync group

This API creates a password sync group based on the specifications provided.

Authorizations:
Personal Access Token
Request Body schema: application/json
id
string

ID of the sync group

name
string

Name of the sync group

passwordPolicyId
string

ID of the password policy

sourceIds
Array of strings

List of password managed sources IDs

created
string or null <date-time>

The date and time this sync group was created

modified
string or null <date-time>

The date and time this sync group was last modified

Responses

Request samples

Content type
application/json
{
  • "name": "Password Sync Group 2",
  • "passwordPolicyId": "2c91808d744ba0ce01746f93b6204501",
  • "sourceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "6881f631-3bd5-4213-9c75-8e05cc3e35dd",
  • "name": "Password Sync Group 2",
  • "passwordPolicyId": "2c91808d744ba0ce01746f93b6204501",
  • "sourceIds": [
    ]
}

Get password sync group by id

This API returns the sync group for the specified ID.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 6881f631-3bd5-4213-9c75-8e05cc3e35dd

The ID of password sync group to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "6881f631-3bd5-4213-9c75-8e05cc3e35dd",
  • "name": "Password Sync Group 1",
  • "passwordPolicyId": "2c91808d744ba0ce01746f93b6204501",
  • "sourceIds": [
    ]
}

Update password sync group by id

This API updates the specified password sync group.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 6881f631-3bd5-4213-9c75-8e05cc3e35dd

The ID of password sync group to update.

Request Body schema: application/json
id
string

ID of the sync group

name
string

Name of the sync group

passwordPolicyId
string

ID of the password policy

sourceIds
Array of strings

List of password managed sources IDs

created
string or null <date-time>

The date and time this sync group was created

modified
string or null <date-time>

The date and time this sync group was last modified

Responses

Request samples

Content type
application/json
{
  • "id": "6881f631-3bd5-4213-9c75-8e05cc3e35dd",
  • "name": "Password Sync Group 2",
  • "passwordPolicyId": "2c91808d744ba0ce01746f93b6204501",
  • "sourceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "6881f631-3bd5-4213-9c75-8e05cc3e35dd",
  • "name": "Password Sync Group 2",
  • "passwordPolicyId": "2c91808d744ba0ce01746f93b6204501",
  • "sourceIds": [
    ]
}

Delete password sync group by id

This API deletes the specified password sync group.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 6881f631-3bd5-4213-9c75-8e05cc3e35dd

The ID of password sync group to delete.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Personal Access Tokens

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

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

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

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

List personal access tokens

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

Authorizations:
Personal Access Token
query Parameters
owner-id
string
Default: null
Example: owner-id=2c9180867b50d088017b554662fb281e

The identity ID of the owner whose personal access tokens should be listed. If "me", the caller should have the following right: 'idn:my-personal-access-tokens:read' If an actual owner ID or if the owner-id parameter is omitted in the request, the caller should have the following right: 'idn:all-personal-access-tokens:read'. If the caller has the following right, then managed personal access tokens associated with owner-id will be retrieved: 'idn:managed-personal-access-tokens:read'

filters
string
Example: filters=lastUsed le 2023-02-05T10:59:27.214Z

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

lastUsed: le, isnull

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create personal access token

This creates a personal access token.

Authorizations:
Personal Access Token
Request Body schema: application/json

Name and scope of personal access token.

name
required
string

The name of the personal access token (PAT) to be created. Cannot be the same as another PAT owned by the user for whom this PAT is being created.

scope
Array of strings or null

Scopes of the personal access token. If no scope is specified, the token will be created with the default scope "sp:scopes:all". This means the personal access token will have all the rights of the owner who created it.

accessTokenValiditySeconds
integer or null <int32> [ 15 .. 43200 ]

Number of seconds an access token is valid when generated using this Personal Access Token. If no value is specified, the token will be created with the default value of 43200.

expirationDate
string or null <date-time>

Date and time, down to the millisecond, when this personal access token will expire. If not provided, the token will expire 6 months after its creation date. The value must be a valid date-time string between the current date and 6 months from the creation date.

Responses

Request samples

Content type
application/json
{
  • "name": "NodeJS Integration",
  • "scope": [
    ],
  • "accessTokenValiditySeconds": 36900,
  • "expirationDate": "2018-01-11T18:45:37.098Z"
}

Response samples

Content type
application/json
{
  • "id": "86f1dc6fe8f54414950454cbb11278fa",
  • "secret": "1d1bef2b9f426383447f64f69349fc7cac176042578d205c256ba3f37c59adb9",
  • "scope": [
    ],
  • "name": "NodeJS Integration",
  • "owner": {
    },
  • "created": "2017-07-11T18:45:37.098Z",
  • "accessTokenValiditySeconds": 36900,
  • "expirationDate": "2018-01-11T18:45:37.098Z"
}

Patch personal access token

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

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The Personal Access Token id

Request Body schema: application/json-patch+json

A list of OAuth client update operations according to the JSON Patch standard.

The following fields are patchable:

  • name
  • scope
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "86f1dc6fe8f54414950454cbb11278fa",
  • "name": "NodeJS Integration",
  • "scope": [
    ],
  • "owner": {
    },
  • "created": "2017-07-11T18:45:37.098Z",
  • "lastUsed": "2017-07-11T18:45:37.098Z",
  • "managed": false,
  • "accessTokenValiditySeconds": 36900,
  • "expirationDate": "2018-01-11T18:45:37.098Z"
}

Delete personal access token

This deletes a personal access token.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: ef38f94347e94562b5bb8424a56397d8

The personal access token id

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Public Identities

Use this API in conjunction with Public Identites Config to enable non-administrators to view identities' publicly visible attributes. With this functionality in place, non-administrators can view identity attributes other than the default attributes (email, lifecycle state, and manager), depending on which identity attributes their organization administrators have made public. This can be helpful for access approvers, certification reviewers, managers viewing their direct reports' access, and source owners viewing their tasks.

Get list of public identities

Get a list of public identities. Set add-core-filters to true to exclude incomplete identities and uncorrelated accounts.

Authorizations:
Personal Access Token
query Parameters
limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=firstname eq "John"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

alias: eq, sw

email: eq, sw

firstname: eq, sw

lastname: eq, sw

add-core-filters
boolean
Default: false

If true, only get identities which satisfy ALL the following criteria in addition to any criteria specified by filters:

  • Should be either correlated or protected.
  • Should not be "spadmin" or "cloudadmin".
  • uid should not be null.
  • lastname should not be null.
  • email should not be null.
sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Public Identities Config

Use this API to implement public identity configuration functionality. With this functionality in place, administrators can make up to 5 identity attributes publicly visible so other non-administrator users can see the relevant information they need to make decisions. This can be helpful for approvers making approvals, certification reviewers, managers viewing their direct reports' access, and source owners viewing their tasks.

By default, non-administrators can select an identity and view the following attributes: email, lifecycle state, and manager. However, it may be helpful for a non-administrator reviewer to see other identity attributes like department, region, title, etc. Administrators can use this API to make those necessary identity attributes public to non-administrators.

For example, a non-administrator deciding whether to approve another identity's request for access to the Workday application, whose access may be restricted to members of the HR department, would want to know whether the identity is a member of the HR department. If an administrator has used Update Public Identity Config to make the "department" attribute public, the approver can see the department and make a decision without requesting any more information.

Get the public identities configuration

Returns the publicly visible attributes of an identity available to request approvers for Access Requests and Certification Campaigns.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "modified": "2018-06-25T20:22:28.104Z",
  • "modifiedBy": {
    }
}

Update the public identities configuration

Updates the publicly visible attributes of an identity available to request approvers for Access Requests and Certification Campaigns.

Authorizations:
Personal Access Token
Request Body schema: application/json
Array of objects (Public Identity Attribute Config)

Up to 5 identity attributes that will be available to everyone in the org for all users in the org.

modified
string or null <date-time>

When this configuration was last modified.

object or null (Identity Reference)

The manager for the identity.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "modified": "2018-06-25T20:22:28.104Z",
  • "modifiedBy": {
    }
}

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "modified": "2018-06-25T20:22:28.104Z",
  • "modifiedBy": {
    }
}

Reports Data Extraction

Use this API to implement reports lifecycle managing and monitoring. With this functionality in place, users can run reports, view their results, and cancel reports in progress. This can be potentially helpful for auditing purposes.

Get report result

Get the report results for a report that was run or is running. Returns empty report result in case there are no active task definitions with used in payload task definition name.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
taskResultId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Unique identifier of the task result which handled report

query Parameters
completed
boolean
Default: false
Example: completed=true

state of task result to apply ordering when results are fetching from the DB

Responses

Response samples

Content type
application/json
{
  • "reportType": "IDENTITIES_DETAILS",
  • "taskDefName": "Identities Details Report",
  • "id": "1e01d272b8084c4fa12fcf8fa898102d",
  • "created": "2023-09-07T42:14:05.122Z",
  • "status": "SUCCESS",
  • "duration": 3681,
  • "rows": 193,
  • "availableFormats": [
    ]
}

Run report

Use this API to run a report according to report input details. If non-concurrent task is already running then it returns, otherwise new task creates and returns.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
reportType
string
Enum: "ACCOUNTS" "IDENTITIES_DETAILS" "IDENTITIES" "IDENTITY_PROFILE_IDENTITY_ERROR" "ORPHAN_IDENTITIES" "SEARCH_EXPORT" "UNCORRELATED_ACCOUNTS"

Use this property to define what report should be processed in the RDE service.

ACCOUNTS (object) or IDENTITIES_DETAILS (object) or IDENTITIES (object) or IDENTITY_PROFILE_IDENTITY_ERROR (object) or ORPHAN_IDENTITIES (object) or SEARCH_EXPORT (object) or UNCORRELATED_ACCOUNTS (object)

The string-object map(dictionary) with the arguments needed for report processing.

Responses

Request samples

Content type
application/json
Example
{
  • "reportType": "ACCOUNTS",
  • "arguments": {
    }
}

Response samples

Content type
application/json
Example
{
  • "reportType": "IDENTITIES_DETAILS",
  • "taskDefName": "Identities Details Report",
  • "type": "QUARTZ",
  • "id": "a248c16fe22222b2bd49615481311111",
  • "created": "2023-09-07T42:14:00.364Z",
  • "description": "A detailed view of the identities in the system.",
  • "parentName": "Audit Report",
  • "launcher": "9832285",
  • "launched": "2023-09-07T42:14:00.521Z",
  • "completed": "2023-09-07T42:14:01.137Z",
  • "messages": [ ],
  • "returns": [ ],
  • "attributes": {
    },
  • "progress": "Initializing..."
}

Cancel report

Cancels a running report.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: a1ed223247144cc29d23c632624b4767

ID of the running Report to cancel

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Get report file

Gets a report in file format.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
taskResultId
required
string
Example: ef38f94347e94562b5bb8424a56397d8

Unique identifier of the task result which handled report

query Parameters
fileFormat
required
string
Enum: "csv" "pdf"
Example: fileFormat=csv

Output format of the requested report file

name
string
Example: name=Identities Details Report

preferred Report file name, by default will be used report name from task result.

auditable
boolean
Default: false
Example: auditable=true

Enables auditing for current report download. Will create an audit event and sent it to the REPORT cloud-audit kafka topic. Event will be created if there is any result present by requested taskResultId.

Responses

Response samples

Content type
application/json
{
  • "detailCode": "400.1 Bad Request Content",
  • "trackingId": "e7eab60924f64aa284175b9fa3309599",
  • "messages": [
    ],
  • "causes": [
    ]
}

Requestable Objects

Use this API to implement requestable object functionality. With this functionality in place, administrators can determine which access items can be requested with the Access Request APIs, along with their statuses. This can be helpful for administrators who are implementing and customizing access request functionality as a way of checking which items are requestable as they are created, assigned, and made available.

Requestable objects list

Get a list of acccess items that can be requested through the Access Request endpoints. Access items are marked with AVAILABLE, PENDING or ASSIGNED with respect to the identity provided using identity-id query parameter. This endpoint only lists roles and access profiles. For gathering requestable entitlements, the Entitlements List API can be used with the segmented-for-identity parameter. Any authenticated token can call this endpoint to see their requestable access items.

Authorizations:
Personal Access Token
query Parameters
identity-id
string
Example: identity-id=e7eab60924f64aa284175b9fa3309599

If present, the value returns only requestable objects for the specified identity.

  • Admin users can call this with any identity ID value.
  • Non-admin users can only specify me or pass their own identity ID value.
  • If absent, returns a list of all requestable objects for the tenant. Only admin users can make such a call. In this case, the available, pending, assigned accesses will not be annotated in the result.
types
Array of strings
Items Enum: "ACCESS_PROFILE" "ROLE"
Example: types=ACCESS_PROFILE,ROLE

Filters the results to the specified type/types, where each type is one of ROLE or ACCESS_PROFILE. If absent, all types are returned. SailPoint may add support for additional types in the future without notice.

term
string
Example: term=Finance Role

Allows searching requestable access items with a partial match on the name or description. If term is provided, then the API will ignore the filter query parameter.

statuses
Array of strings (RequestableObjectRequestStatus-2)
Items Enum: "AVAILABLE" "PENDING" "ASSIGNED" null
Example: statuses=ASSIGNED,PENDING

Filters the result to the specified status/statuses, where each status is one of AVAILABLE, ASSIGNED, or PENDING. Specifying this parameter without also specifying an identity-id parameter results in an error. SailPoint may add additional statuses in the future without notice.

limit
integer <int32> [ 0 .. 250 ]
Default: 250
Example: limit=250

Max number of results to return. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=name sw "bob"

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, in, sw

sorters
string <comma-separated>
Example: sorters=name

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Roles

Use this API to implement and customize role functionality. With this functionality in place, administrators can create roles and configure them for use throughout Identity Security Cloud. Identity Security Cloud can use established criteria to automatically assign the roles to qualified users. This enables users to get all the access they need quickly and securely and administrators to spend their time on other tasks.

Entitlements represent the most granular level of access in Identity Security Cloud. Access profiles represent the next level and often group entitlements. Roles represent the broadest level of access and often group access profiles.

For example, an Active Directory source in Identity Security Cloud can have multiple entitlements: the first, 'Employees,' may represent the access all employees have at the organization, and a second, 'Developers,' may represent the access all developers have at the organization.

An administrator can then create a broader set of access in the form of an access profile, 'AD Developers' grouping the 'Employees' entitlement with the 'Developers' entitlement.

An administrator can then create an even broader set of access in the form of a role grouping the 'AD Developers' access profile with another profile, 'GitHub Developers,' grouping entitlements for the GitHub source.

When users only need Active Directory employee access, they can request access to the 'Employees' entitlement.

When users need both Active Directory employee and developer access, they can request access to the 'AD Developers' access profile.

When users need both the 'AD Developers' access profile and the 'GitHub Developers' access profile, they can request access to the role grouping both.

Roles often represent positions within organizations. For example, an organization's accountant can access all the tools the organization's accountants need with the 'Accountant' role. If the accountant switches to engineering, a qualified member of the organization can quickly revoke the accountant's 'Accountant' access and grant access to the 'Engineer' role instead, granting access to all the tools the organization's engineers need.

In Identity Security Cloud, adminstrators can use the Access drop-down menu and select Roles to view, configure, and delete existing roles, as well as create new ones. Administrators can enable and disable the role, and they can also make the following configurations:

  • Manage Access: Manage the role's access by adding or removing access profiles.

  • Define Assignment: Define the criteria Identity Security Cloud uses to assign the role to identities. Use the first option, 'Standard Criteria,' to provide specific criteria for assignment like specific account attributes, entitlements, or identity attributes. Use the second, 'Identity List,' to specify the identities for assignment.

  • Access Requests: Configure roles to be requestable and establish an approval process for any requests that the role be granted or revoked. Do not configure a role to be requestable without establishing a secure access request approval process for that role first.

Refer to Working with Roles for more information about roles.

List roles

This API returns a list of Roles.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
for-subadmin
string
Example: for-subadmin=5168015d32f890ca15812c9180835d2e

If provided, filters the returned list according to what is visible to the indicated ROLE_SUBADMIN Identity. The value of the parameter is either an Identity ID, or the special value me, which is shorthand for the calling Identity's ID. A 400 Bad Request error is returned if the for-subadmin parameter is specified for an Identity that is not a subadmin.

limit
integer <int32> [ 0 .. 50 ]
Default: 50
Example: limit=50

Note that for this API the maximum value for limit is 50. See V3 API Standard Collection Parameters for more information.

offset
integer <int32> >= 0
Default: 0

Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

count
boolean
Default: false
Example: count=true

If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

See V3 API Standard Collection Parameters for more information.

filters
string
Example: filters=requestable eq false

Filter results using the standard syntax described in V3 API Standard Collection Parameters

Filtering is supported for the following fields and operators:

id: eq, in

name: eq, sw

created: gt, ge, le

modified: lt, ge, le

owner.id: eq, in

requestable: eq

dimensional: eq

sorters
string <comma-separated>
Example: sorters=name,-modified

Sort results using the standard syntax described in V3 API Standard Collection Parameters

Sorting is supported for the following fields: name, created, modified

for-segment-ids
string <comma-separated>
Example: for-segment-ids=0b5c9f25-83c6-4762-9073-e38f7bb2ae26,2e8d8180-24bc-4d21-91c6-7affdb473b0d

If present and not empty, additionally filters Roles to those which are assigned to the Segment(s) with the specified IDs.

If segmentation is currently unavailable, specifying this parameter results in an error.

include-unsegmented
boolean
Default: true

Whether or not the response list should contain unsegmented Roles. If for-segment-ids is absent or empty, specifying include-unsegmented as false results in an error.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a role

This API creates a role. In addition, a ROLE_SUBADMIN may not create a role including an access profile if that access profile is associated with a source the ROLE_SUBADMIN is not associated with themselves.

The maximum supported length for the description field is 2000 characters. Longer descriptions will be preserved for existing roles. However, any new roles as well as any updates to existing descriptions will be limited to 2000 characters.

Authorizations:
Personal Access Token
Request Body schema: application/json
id
string

The id of the Role. This field must be left null when creating an Role, otherwise a 400 Bad Request error will result.

name
required
string <= 128 characters

The human-readable display name of the Role

description
string or null

A human-readable description of the Role

required
object (OwnerReference)

Owner of the object.

Array of objects or null (AdditionalOwnerRef)

List of additional owner references beyond the primary owner. Each entry may be an identity (IDENTITY) or a governance group (GOVERNANCE_GROUP).

Array of objects or null (AccessProfileRef)
Array of objects (EntitlementRef)
object or null (RoleMembershipSelector)

When present, specifies that the Role is to be granted to Identities which either satisfy specific criteria or which are members of a given list of Identities.

object or null

This field is not directly modifiable and is generally expected to be null. In very rare instances, some Roles may have been created using membership selection criteria that are no longer fully supported. While these Roles will still work, they should be migrated to STANDARD or IDENTITY_LIST selection criteria. This field exists for informational purposes as an aid to such migration.

enabled
boolean
Default: false

Whether the Role is enabled or not.

requestable
boolean
Default: false

Whether the Role can be the target of access requests.

object (RequestabilityForRole)
object (RevocabilityForRole)
segments
Array of strings or null

List of IDs of segments, if any, to which this Role is assigned.

dimensional
boolean or null
Default: false

Whether the Role is dimensional.

Array of objects or null (DimensionRef)

List of references to dimensions to which this Role is assigned. This field is only relevant if the Role is dimensional.

object (AttributeDTOList)
privilegeLevel
string or null

The privilege level of the role, if applicable.

Responses

Request samples

Content type
application/json
{
  • "id": "2c918086749d78830174a1a40e121518",
  • "name": "Role 2567",
  • "description": "Urna amet cursus pellentesque nisl orci maximus lorem nisl euismod fusce morbi placerat adipiscing maecenas nisi tristique et metus et lacus sed morbi nunc nisl maximus magna arcu varius sollicitudin elementum enim maecenas nisi id ipsum tempus fusce diam ipsum tortor.",
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "accessProfiles": [
    ],
  • "entitlements": [
    ],
  • "membership": {
    },
  • "legacyMembershipInfo": {
    },
  • "enabled": true,
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "dimensional": false,
  • "dimensionRefs": [
    ],
  • "accessModelMetadata": {
    },
  • "privilegeLevel": "High"
}

Response samples

Content type
application/json
{
  • "id": "2c918086749d78830174a1a40e121518",
  • "name": "Role 2567",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "description": "Urna amet cursus pellentesque nisl orci maximus lorem nisl euismod fusce morbi placerat adipiscing maecenas nisi tristique et metus et lacus sed morbi nunc nisl maximus magna arcu varius sollicitudin elementum enim maecenas nisi id ipsum tempus fusce diam ipsum tortor.",
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "accessProfiles": [
    ],
  • "entitlements": [
    ],
  • "membership": {
    },
  • "legacyMembershipInfo": {
    },
  • "enabled": true,
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "dimensional": false,
  • "dimensionRefs": [
    ],
  • "accessModelMetadata": {
    },
  • "privilegeLevel": "High"
}

Get role

Get a role by ID. A user with ROLE_SUBADMIN authority may only call this API if all access profiles included in the role are associated to sources with management workgroups of the ROLE_SUBADMIN is a member of.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 2c91808a7813090a017814121e121518

Role ID.

Responses

Response samples

Content type
application/json
{
  • "id": "2c918086749d78830174a1a40e121518",
  • "name": "Role 2567",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "description": "Urna amet cursus pellentesque nisl orci maximus lorem nisl euismod fusce morbi placerat adipiscing maecenas nisi tristique et metus et lacus sed morbi nunc nisl maximus magna arcu varius sollicitudin elementum enim maecenas nisi id ipsum tempus fusce diam ipsum tortor.",
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "accessProfiles": [
    ],
  • "entitlements": [
    ],
  • "membership": {
    },
  • "legacyMembershipInfo": {
    },
  • "enabled": true,
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "dimensional": false,
  • "dimensionRefs": [
    ],
  • "accessModelMetadata": {
    },
  • "privilegeLevel": "High"
}

Patch role

Update an existing role, using the JSON Patch syntax. The following fields are patchable:

  • name
  • description
  • enabled
  • owner
  • additionalOwners
  • accessProfiles
  • entitlements
  • membership
  • requestable
  • accessRequestConfig
  • revokeRequestConfig
  • segments
  • accessModelMetadata

A user with ROLE_SUBADMIN authority may only call this API if all access profiles included in the role are associated to sources with management workgroups of the ROLE_SUBADMIN is a member of.

The maximum supported length for the description field is 2000 characters. ISC preserves longer descriptions for existing roles. However, any new roles as well as any updates to existing descriptions are limited to 2000 characters.

When you use this API to modify a role's membership identities, you can only modify up to a limit of 500 membership identities at a time.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 2c91808a7813090a017814121e121518

Role ID to patch

Request Body schema: application/json-patch+json
Array
op
required
string
Enum: "add" "remove" "replace" "move" "copy" "test"

The operation to be performed

path
required
string

A string JSON Pointer representing the target path to an element to be affected by the operation

string (string) or boolean (boolean) or integer (integer) or object (object) or (Array of array (strings or integers or objects))

The value to be used for the operation, required for "add" and "replace" operations

Responses

Request samples

Content type
application/json-patch+json
Example

This example shows how multiple fields may be updated with a single patch call.

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c918086749d78830174a1a40e121518",
  • "name": "Role 2567",
  • "created": "2021-03-01T22:32:58.104Z",
  • "modified": "2021-03-02T20:22:28.104Z",
  • "description": "Urna amet cursus pellentesque nisl orci maximus lorem nisl euismod fusce morbi placerat adipiscing maecenas nisi tristique et metus et lacus sed morbi nunc nisl maximus magna arcu varius sollicitudin elementum enim maecenas nisi id ipsum tempus fusce diam ipsum tortor.",
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "accessProfiles": [
    ],
  • "entitlements": [
    ],
  • "membership": {
    },
  • "legacyMembershipInfo": {
    },
  • "enabled": true,
  • "requestable": true,
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    },
  • "segments": [
    ],
  • "dimensional": false,
  • "dimensionRefs": [
    ],
  • "accessModelMetadata": {
    },
  • "privilegeLevel": "High"
}