API docs by Redocly

Identity Security Cloud Beta API (3.1.0-beta)

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. These APIs are in beta and are subject to change. 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 Model Metadata

Use this API to create and manage metadata attributes for your Access Model. Access Model Metadata allows you to add contextual information to your ISC Access Model items using pre-defined metadata for risk, regulations, privacy levels, etc., or by creating your own metadata attributes to reflect the unique needs of your organization. This release of the API includes support for entitlement metadata. Support for role and access profile metadata will be introduced in a subsequent release.

Common usages for Access Model metadata include:

  • Organizing and categorizing access items to make it easier for your users to search for and find the access rights they want to request, certify, or manage.

  • Providing richer information about access that is being acted on to allow stakeholders to make better decisions when approving, certifying, or managing access rights.

  • Identifying access that may requires additional approval requirements or be subject to more frequent review.

List access model metadata attributes

Get a list of Access Model Metadata Attributes

Authorizations:
Personal Access TokenClient Credentials
query Parameters
filters
string
Example: filters=name eq "Privacy"

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

Filtering is supported for the following fields and operators:

key: eq

name: eq

type: eq

status: eq

objectTypes: eq

Supported composite operators are and, or

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

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

Sorting is supported for the following fields: name, key

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create access model metadata attribute

Create a new Access Model Metadata Attribute.

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

Attribute to create

key
string

Technical name of the Attribute. This is unique and cannot be changed after creation.

name
string

The display name of the key.

multiselect
boolean
Default: false

Indicates whether the attribute can have multiple values.

status
string

The status of the Attribute.

type
string

The type of the Attribute. This can be either "custom" or "governance".

objectTypes
Array of strings or null

An array of object types this attributes values can be applied to. Possible values are "all" or "entitlement". Value "all" means this attribute can be used with all object types that are supported.

description
string

The description of the Attribute.

Array of objects or null (AttributeValueDTO)

Responses

Request samples

Content type
application/json
{
  • "key": "iscPrivacy",
  • "name": "Privacy",
  • "multiselect": false,
  • "status": "active",
  • "type": "governance",
  • "objectTypes": [
    ],
  • "description": "Specifies the level of privacy associated with an access item.",
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "key": "iscPrivacy",
  • "name": "Privacy",
  • "multiselect": false,
  • "status": "active",
  • "type": "governance",
  • "objectTypes": [
    ],
  • "description": "Specifies the level of privacy associated with an access item.",
  • "values": [
    ]
}

Get access model metadata attribute

Get single Access Model Metadata Attribute

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

Responses

Response samples

Content type
application/json
{
  • "key": "iscPrivacy",
  • "name": "Privacy",
  • "multiselect": false,
  • "status": "active",
  • "type": "governance",
  • "objectTypes": [
    ],
  • "description": "Specifies the level of privacy associated with an access item.",
  • "values": [
    ]
}

Update access model metadata attribute

Update an existing Access Model Metadata Attribute.
The following fields are patchable: name, description, multiselect, values

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

Request Body schema: application/json-patch+json

JSON Patch array to apply

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
{
  • "key": "iscPrivacy",
  • "name": "Privacy",
  • "multiselect": false,
  • "status": "active",
  • "type": "governance",
  • "objectTypes": [
    ],
  • "description": "Specifies the level of privacy associated with an access item.",
  • "values": [
    ]
}

List access model metadata values

Get a list of Access Model Metadata Attribute Values

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

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.

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 access model metadata value

Create a new value for an existing Access Model Metadata Attribute.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

Request Body schema: application/json

Attribute value to create

value
string

Technical name of the Attribute value. This is unique and cannot be changed after creation.

name
string

The display name of the Attribute value.

status
string

The status of the Attribute value.

Responses

Request samples

Content type
application/json
{
  • "value": "public",
  • "name": "Public",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "value": "public",
  • "name": "Public",
  • "status": "active"
}

Get access model metadata value

Get single Access Model Metadata Attribute Value

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

value
required
string
Example: public

Technical name of the Attribute value.

Responses

Response samples

Content type
application/json
{
  • "value": "public",
  • "name": "Public",
  • "status": "active"
}

Update access model metadata value

Update an existing Access Model Metadata Attribute Value.
The following fields are patchable: name

Authorizations:
Personal Access TokenClient Credentials
path Parameters
key
required
string
Example: iscPrivacy

Technical name of the Attribute.

value
required
string
Example: public

Technical name of the Attribute value.

Request Body schema: application/json-patch+json

JSON Patch array to apply

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
{
  • "value": "public",
  • "name": "Public",
  • "status": "active"
}

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

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 A token with API, ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API. In addition, a 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 token with API, ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to invoke this API. In addition, a SOURCE_SUBADMIN token 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.

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": [
    ]
}

Update access profile(s) requestable field.

This API initiates a bulk update of field requestable for one or more Access Profiles.

If any of the indicated Access Profiles is exists in Organization,then those Access Profiles will be added in updated list of the response.Requestable field of these Access Profiles marked as true or false.

If any of the indicated Access Profiles is not does not exists in Organization,then those Access Profiles will be added in notFound list of the response. Access Profiles marked as notFound will not be updated. A SOURCE_SUBADMIN user may only use this API to update Access Profiles which are associated with Sources they are able to administer.

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

Access Profile ID.

requestable
boolean

Access Profile is requestable or not.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

List access profile's entitlements

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

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

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

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

sorters
string <comma-separated>

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

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

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>

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.

object
created
string <date-time>

Date and time comment was created.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a comment.",
  • "author": {
    },
  • "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.

object
created
string <date-time>

Date and time comment was created.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a comment.",
  • "author": {
    },
  • "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.

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": "string",
  • "comment": "string"
}

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.

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 Request Identity Metrics

Use this API to implement access request identity metrics functionality. With this functionality in place, access request reviewers can see relevant details about the requested access item and associated source activity. This allows reviewers to see how many of the identities who share a manager with the access requester have this same type of access and how many of them have had activity in the related source. This additional context about whether the access has been granted before and how often it has been used can help those approving access requests make more informed decisions.

Return access request identity metrics

Use this API to return information access metrics.

Authorizations:
Personal Access Token
path Parameters
identityId
required
string
Example: 7025c863-c270-4ba6-beea-edf3cb091573

Manager's identity ID.

requestedObjectId
required
string
Example: 2db501be-f0fb-4cc5-a695-334133c52891

Requested access item's ID.

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

Requested access item's type.

Responses

Response samples

Content type
application/json
{ }

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
{ }

Close access request

This endpoint closes access requests that are stuck in a pending state. It can be used throughout a request's lifecycle even after the approval state, unlike the Cancel Access Request endpoint.

To find pending access requests with the UI, navigate to Search and use this query: status: Pending AND "Access Request". Use the Column Chooser to select 'Tracking Number', and use the 'Download' button to export a CSV containing the tracking numbers.

To find pending access requests with the API, use the List Account Activities endpoint.

Input the IDs from either source.

To track the status of endpoint requests, navigate to Search and use this query: name:"Close Identity Requests". Search will include "Close Identity Requests Started" audits when requests are initiated and "Close Identity Requests Completed" audits when requests are completed. The completion audit will list the identity request IDs that finished in error.

This API triggers the Provisioning Completed event trigger for each access request that is closed.

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

Access Request IDs for the requests to be closed. Accepts 1-500 Identity Request IDs per request.

message
string
Default: "The IdentityNow Administrator manually closed this request."

Reason for closing the access request. Displayed under Warnings in IdentityNow.

executionStatus
string
Default: "Terminated"
Enum: "Terminated" "Completed"

The request's provisioning status. Displayed as Stage in IdentityNow.

completionStatus
string
Default: "Failure"
Enum: "Success" "Incomplete" "Failure"

The request's overall status. Displayed as Status in IdentityNow.

Responses

Request samples

Content type
application/json
{
  • "accessRequestIds": [
    ],
  • "executionStatus": "Terminated",
  • "completionStatus": "Failure",
  • "message": "The IdentityNow Administrator manually closed this request."
}

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
[
  • {
    }
]

Access request status for administrators

Use this API to get access request statuses of all the access requests in the org based on the specified query parameters. Any user with user level ORG_ADMIN or scope idn:access-request-administration:read can access this endpoint to get the access request statuses

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:

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

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

status: in, eq, ne

created: eq, in, ge, gt, le, lt, 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: created, modified, accountActivityItemId, name, accessRequestId

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

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

header Parameters
X-SailPoint-Experimental
required
string
Default: true
Example: true

Use this header to enable this experimental API.

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 that occur 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

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

requested-by
string

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

regarding-identity
string

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.

type
string

The type of account activity.

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

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, gt, 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>

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 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": null,
  • "items": [
    ],
  • "executionStatus": "COMPLETED",
  • "clientMetadata": {
    },
  • "cancelable": true,
  • "cancelComment": {
    }
}

Account Aggregations

Use this API to implement account aggregation progress tracking functionality. With this functionality in place, administrators can view in-progress account aggregations, their statuses, and their relevant details.

An account aggregation refers to the process Identity Security Cloud uses to gather and load account data from a source into Identity Security Cloud.

Whenever Identity Security Cloud is in the process of aggregating a source, it adds an entry to the Aggregation Activity Log, along with its relevant details. To view aggregation activity, administrators can select the Connections drop-down menu, select Sources, and select the relevant source, select its Import Data tab, and select Account Aggregation. In Account Aggregation, administrators can view the account aggregations' statuses and details in the Account Activity Log.

Refer to Loading Account Data for more information about account aggregations.

In-progress account aggregation status

This API returns the status of an in-progress account aggregation, along with the total number of NEW, CHANGED and DELETED accounts found since the previous aggregation, and the number of those accounts that have been processed so far.

Accounts that have not changed since the previous aggregation are not included in totalAccounts and processedAccounts counts returned by this API. This is distinct from Accounts Scanned shown in the Aggregation UI, which indicates total accounts scanned regardless of whether they changed or not.

Since this endpoint reports on the status of an in-progress account aggregation, totalAccounts and processedAccounts may change between calls to this endpoint.

Only available up to an hour after the aggregation completes. May respond with 404 Not Found after that.

A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN or DASHBOARD authority is required to call this API.

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

The account aggregation id

Responses

Response samples

Content type
application/json
{
  • "start": "2021-01-31T14:30:05.104Z",
  • "status": "ACCOUNTS_COLLECTED",
  • "totalAccounts": 520,
  • "processedAccounts": 150
}

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 Deprecated

List accounts.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
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.

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=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

sourceId: eq, in, sw

uncorrelated: eq

entitlements: eq

origin: eq, in

manuallyCorrelated: eq

hasEntitlements: 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

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, hasEntitlements, entitlements, origin, identity.name, identity.identityState, identity.correlated, source.displayableName, source.authoritative, source.connectionType, sourceOwner.name

Responses

Response samples

Content type
application/json
Example

List of slim accounts that would result with detailLevel = SLIM

[
  • {
    }
]

Create account Deprecated

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

The sourceId where this account will be created must be included 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 Deprecated

Use this API to return the details for a single account by its ID.
A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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": "2023-01-03T21:16:22.432Z",
  • "modified": "2023-01-03T21:16:22.432Z",
  • "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 Deprecated

Use this API to update account details. A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.

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
{
  • "Uncorrelate account": {
    },
  • "Reassign account": {
    },
  • "Add account attribute": {
    },
  • "Replace account attribute": {
    },
  • "Remove account attribute": {
    }
}

Response samples

Content type
application/json
{ }

Update account Deprecated

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

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

A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.

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
attributes
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 Deprecated

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. A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.

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 Deprecated

This API returns entitlements of the account.
A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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

The account id

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reload account Deprecated

This API asynchronously reloads the account directly from the connector and performs a one-time aggregation process.
A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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 Deprecated

This API submits a task to enable account and returns the task ID.
A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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.

Responses

Request samples

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

Response samples

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

Disable account Deprecated

This API submits a task to disable the account and returns the task ID.
A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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.

Responses

Request samples

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

Response samples

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

Unlock account Deprecated

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. A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or HELPDESK authority is required to call this API.

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"
}

Remove account

Use this endpoint to remove accounts from the system without provisioning changes to the source. Accounts that are removed could be re-created during the next aggregation.

This endpoint is good for:

  • Removing accounts that no longer exist on the source.
  • Removing accounts that won't be aggregated following updates to the source configuration.
  • Forcing accounts to be re-created following the next aggregation to re-run account processing, support testing, etc.
Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: c350d6aa4f104c61b062cb632421ad10

The account id

Responses

Response samples

Content type
application/json
{
  • "type": "TASK_RESULT",
  • "id": "464ae7bf791e49fdb74606a2e4a89635",
  • "name": null
}

Enable idn account for identity Deprecated

This API submits a task to enable IDN account for a single identity.

Learn more about enabling identities here
Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 2c91808384203c2d018437e631158309

The identity id.

Responses

Response samples

Content type
application/json
{ }

Disable idn account for identity Deprecated

This API submits a task to disable IDN account for a single identity.

Learn more about disabling identities here
Authorizations:
Personal Access TokenClient Credentials
path Parameters
id
required
string
Example: 2c91808384203c2d018437e631158309

The identity id.

Responses

Response samples

Content type
application/json
{ }

Enable idn accounts for identities Deprecated

This API submits tasks to enable IDN account for each identity provided in the request body.

Learn more about enabling identities here
Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
identityIds
Array of strings

The ids of the identities for which enable/disable accounts.

Responses

Request samples

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

Response samples

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

Disable idn accounts for identities Deprecated

This API submits tasks to disable IDN account for each identity provided in the request body.

Learn more about disabling identities here
Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
identityIds
Array of strings

The ids of the identities for which enable/disable accounts.

Responses

Request samples

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

Response samples

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

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

Upload 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": [
    ]
}

Retrieve 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

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

Get discovered application by id

Get the discovered application, along with with its associated sources, based on the provided ID.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 123e4567-e89b-12d3-a456-426655440000

Discovered application's ID.

Responses

Response samples

Content type
application/json
{
  • "id": "app-123",
  • "name": "Example App",
  • "discoverySource": "csv",
  • "discoveredVendor": "Example Vendor",
  • "description": "An application for managing examples.",
  • "recommendedConnectors": [
    ],
  • "discoveredAt": "2023-07-01T12:00:00Z",
  • "createdAt": "2024-06-01T12:00:00Z",
  • "status": "ACTIVE",
  • "associatedSources": [
    ],
  • "riskScore": 1,
  • "isBusiness": false,
  • "totalSigninsCount": 1,
  • "riskLevel": "Low"
}

Patch discovered application by id

Update an existing discovered application by using a limited version of the JSON Patch syntax. You can patch these fields: - associatedSources - dismissed

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 123e4567-e89b-12d3-a456-426655440000

Discovered application's ID.

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

The operation to be performed

path
required
string

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

string (string) or boolean (boolean) or Array of array (strings)

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 use patch to set the dismissal status of a correlated application to true.

[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "app-123",
  • "name": "Example App",
  • "discoverySource": "csv",
  • "discoveredVendor": "Example Vendor",
  • "description": "An application for managing examples.",
  • "recommendedConnectors": [
    ],
  • "discoveredAt": "2023-07-01T12:00:00Z",
  • "createdAt": "2024-06-01T12:00:00Z",
  • "status": "ACTIVE",
  • "associatedSources": [
    ],
  • "riskScore": 1,
  • "isBusiness": false,
  • "totalSigninsCount": 1,
  • "riskLevel": "Low"
}

Approvals

Use this API to implement approval functionality. With this functionality in place, you can get generic approvals and modify them.

The main advantages this API has vs Access Request Approvals are that you can use it to get generic approvals individually or in batches and make changes to those approvals.

Apps

Use this API to implement source application functionality. With this functionality in place, you can create, customize, and manage applications within sources.

Get source app by id

This API returns a source app by its ID.

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

ID of the source app

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808874ff91550175097daaec161c",
  • "cloudAppId": "9854520",
  • "name": "my app",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "enabled": true,
  • "provisionRequestEnabled": true,
  • "description": "the source app for engineers",
  • "matchAllAccounts": true,
  • "appCenterEnabled": true,
  • "accountSource": {
    },
  • "owner": {
    }
}

Patch source app by id

This API updates an existing source app using JSON Patch syntax. The following fields are patchable: name, description, enabled, owner, provisionRequestEnabled, appCenterEnabled, accountSource, matchAllAccounts and accessProfiles. Name, description and owner can't be empty or null.

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

ID of the source app 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": "2c91808874ff91550175097daaec161c",
  • "cloudAppId": "9854520",
  • "name": "my app",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "enabled": true,
  • "provisionRequestEnabled": true,
  • "description": "the source app for engineers",
  • "matchAllAccounts": true,
  • "appCenterEnabled": true,
  • "accessProfiles": [
    ],
  • "accountSource": {
    },
  • "owner": {
    }
}

Delete source app by id

Use this API to delete a specific source app

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

source app ID.

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808874ff91550175097daaec161c",
  • "cloudAppId": "9854520",
  • "name": "my app",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "enabled": true,
  • "provisionRequestEnabled": true,
  • "description": "the source app for engineers",
  • "matchAllAccounts": true,
  • "appCenterEnabled": true,
  • "accountSource": {
    },
  • "owner": {
    }
}

Bulk update source apps

This API updates source apps using JSON Patch syntax. It can update up to 50 source apps in a batch. The following fields can be updated: name, description, enabled, owner, provisionRequestEnabled, appCenterEnabled, accountSource, matchAllAccounts, and accessProfiles. Name, description and owner can't be empty or null.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
appIds
required
Array of strings <= 50 items

List of source app ids to update

required
Array of objects (Json Patch Operation)

The JSONPatch payload used to update the source app.

Responses

Request samples

Content type
application/json
{
  • "appIds": [
    ],
  • "jsonPatch": [
    ]
}

Response samples

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

List assigned source apps

This API returns the list of source apps assigned for logged in user.

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.

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.

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.

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: id, name, created, modified, accountSource.id

filters
string
Example: filters=name eq "source app 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, in

name: eq, in, co, sw

created: gt, lt, ge, le

modified: gt, lt, ge, le

accountSource.id: eq, in

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available source apps

This API returns the list of source apps available for access request.

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.

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.

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.

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: id, name, created, modified, owner.id, accountSource.id

filters
string
Example: filters=name eq "source app 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, in

name: eq, in, co, sw

created: gt, lt, ge, le

modified: gt, lt, ge, le

accountSource.id: eq, in

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create source app

This endpoint creates a source app using the given source app payload

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

The source app name

description
required
string

The description of the source app

matchAllAccounts
boolean
Default: false

True if the source app match all accounts

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "new app name",
  • "description": "app description",
  • "matchAllAccounts": true,
  • "accountSource": {
    }
}

Response samples

Content type
application/json
{
  • "id": "2c91808874ff91550175097daaec161c",
  • "cloudAppId": "9854520",
  • "name": "my app",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "enabled": true,
  • "provisionRequestEnabled": true,
  • "description": "the source app for engineers",
  • "matchAllAccounts": true,
  • "appCenterEnabled": true,
  • "accountSource": {
    },
  • "owner": {
    }
}

List all source apps

This API returns the list of all source apps for the org.

A token with ORG_ADMIN authority is required to call this API.

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.

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.

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.

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: id, name, created, modified, owner.id, accountSource.id

filters
string
Example: filters=enabled eq true

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, co, sw

created: gt, lt, ge, le

modified: gt, ge, le

owner.id: eq, in

enabled: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List access profiles for the specified source app

This API returns the list of access profiles for the specified source app

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

ID of the source app

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.

filters
string
Example: filters=name eq "developer access profile"

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

created: gt, lt, ge, le

modified: gt, lt, ge, le

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bulk remove access profiles from the specified source app

This API returns the final list of access profiles for the specified source app after removing

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

ID of the source app

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.

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "c9575abb5e3a4e3db82b2f989a738aa2",
  • "c9dc28e148a24d65b3ccb5fb8ca5ddd9"
]

Response samples

Content type
application/json
[
  • {
    }
]

Patch user app by id

This API updates an existing user app using JSON Patch syntax. The following fields are patchable: account

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

ID of the user app 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
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "2c91808874ff91550175097daaec161c",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "hasMultipleAccounts": false,
  • "useForPasswordManagement": true,
  • "provisionRequestEnabled": true,
  • "appCenterEnabled": true,
  • "sourceApp": {
    },
  • "source": {
    },
  • "account": {
    },
  • "owner": {
    }
}

List available accounts for user app

This API returns the list of available accounts for the specified user app. The user app needs to belong lo logged in user.

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

ID of the user app

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.

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.

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List owned user apps

This API returns the list of user apps assigned to logged in user

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.

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.

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.

filters
string
Example: filters=name eq "user app 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

ownerName: eq, sw

ownerAlias: eq, sw

accountId: eq

sourceAppId: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all user apps

This API returns the list of all user apps with specified filters. This API must be used with filters query parameter.

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.

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.

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.

filters
required
string
Example: filters=name eq "user app 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

ownerId: eq

ownerName: eq, sw

ownerAlias: eq, sw

accountId: eq

sourceAppId: eq

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Auth Profile

Use this API to implement Auth Profile functionality. With this functionality in place, users can read authentication profiles and make changes to them.

An authentication profile represents an identity profile's authentication configuration. When the identity profile is created, its authentication profile is also created. An authentication profile includes information like its authentication profile type (BLOCK, MFA, NON_PTA, PTA`) and settings controlling whether or not it blocks access from off network or untrusted geographies.

Get list of auth profiles.

This API returns a list of auth profiles.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get auth profile.

This API returns auth profile information.

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

ID of the Auth Profile to get.

Responses

Response samples

Content type
application/json
{
  • "name": "EndToEnd-Profile",
  • "offNetwork": true,
  • "untrustedGeography": true,
  • "applicationId": "2c91808458ae7a4f0158b1bbf8af0628",
  • "applicationName": "EndToEnd-Source",
  • "type": "PTA",
  • "strongAuthLogin": true
}

Patch a specified auth profile

This API updates an existing Auth Profile. The following fields are patchable: offNetwork, untrustedGeography, applicationId, applicationName, type

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

ID of the Auth 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
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "name": "EndToEnd-Profile",
  • "offNetwork": true,
  • "untrustedGeography": true,
  • "applicationId": "2c91808458ae7a4f0158b1bbf8af0628",
  • "applicationName": "EndToEnd-Source",
  • "type": "PTA",
  • "strongAuthLogin": true
}

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 Deprecated

Use this API to get a list of campaigns. The API can provide increased level of detail for each campaign for the correct provided query. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN, CERT_ADMIN or REPORT_ADMIN authority is required to call this API.

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 campaign Deprecated

Use this API to create a certification campaign with the information provided in the request body. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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

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"
}

Delete campaigns Deprecated

Use this API to delete certification campaigns whose IDs are specified in the provided list of campaign IDs. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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
{ }

Get campaign Deprecated

Use this API to get information for an existing certification campaign by the campaign's ID. Though this endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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

ID of the campaign to be retrieved.

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 Deprecated

Use this API to update individual fields on a certification campaign, using the JSON Patch standard. Though this endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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

ID of the campaign 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
object

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
}

Activate a campaign Deprecated

Use this API to submit a job to activate the certified campaign with the specified ID. The campaign must be staged. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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 Deprecated

:::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. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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
{ }

Run campaign remediation scan Deprecated

Use this API to run a remediation scan task for a certification campaign. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN, CERT_ADMIN or REPORT_ADMIN authority is required to call this API.

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
{ }

Reassign certifications Deprecated

This API reassigns the specified certifications from one identity to another. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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"
}

Get campaign reports Deprecated

Use this API to fetch all reports for a certification campaign by campaign ID. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN, CERT_ADMIN or REPORT_ADMIN authority is required to call this API.

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 Deprecated

Use this API to run a report for a certification campaign. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN, CERT_ADMIN or REPORT_ADMIN authority is required to call this API.

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 report to run.

Responses

Response samples

Content type
application/json
{ }

Get campaign reports configuration Deprecated

Use this API to fetch the configuration for certification campaign reports. The configuration includes only one element - identity attributes defined as custom report columns. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token

Responses

Response samples

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

Set campaign reports configuration Deprecated

Use this API to overwrite the configuration for campaign reports. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": [
    ]
}

List campaign templates Deprecated

Use this API to get a list of all campaign templates. Scope can be reduced through standard V3 query params. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

The endpoint returns all campaign templates matching the query parameters.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create a campaign template Deprecated

Use this API to create a campaign template based on campaign. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": {
    }
}

Get a campaign template Deprecated

Use this API to fetch a certification campaign template by ID. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": {
    }
}

Update a campaign template Deprecated

Use this API to update individual fields on a certification campaign template, using the JSON Patch standard. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": {
    }
}

Delete a campaign template Deprecated

Use this API to delete a certification campaign template by ID. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": [
    ]
}

Generate a campaign from template Deprecated

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.

Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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"
}

Get campaign template schedule Deprecated

Use this API to get the schedule for a certification campaign template. The API returns a 404 if there is no schedule set. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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 Deprecated

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. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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

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 <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 Deprecated

Use this API to delete the schedule for a certification campaign template. The API returns a 404 if there is no schedule set. Though this Beta endpoint has been deprecated, you can find its V3 equivalent here.

A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API.

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": [
    ]
}

Certifications

Use this API to implement certification functionality. This API provides specific functionality that improves an organization's ability to manage its certification process.

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.

This API enables administrators and reviewers to get useful information about certifications at a high level, such as the reviewers involved, and at a more granular level, such as the permissions affected by changes to entitlements within those certifications. It also provides the useful ability to reassign identities and items within certifications to other reviewers, rather than reassigning the entire certifications themselves.

Refer to Managing User Accounts for more information about accounts.

Reassign certifications asynchronously Deprecated

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. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. 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": "abcd-ef12-3456",
  • "certificationId": "ef38f94347e94562b5bb8424a56397d8",
  • "type": "REASSIGN",
  • "status": "QUEUED",
  • "errors": [ ]
}

Certification task status Deprecated

This API returns the status of a certification task. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string

The identity campaign certification ID

taskId
required
string

The certification task ID

Responses

Response samples

Content type
application/json
{
  • "id": "abcd-ef12-3456",
  • "certificationId": "ef38f94347e94562b5bb8424a56397d8",
  • "type": "REASSIGN",
  • "status": "QUEUED",
  • "errors": [ ]
}

Pending certification tasks Deprecated

This API returns the status of all pending (QUEUED or IN_PROGRESS) tasks for an identity campaign certification. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. Reviewers for this certification can also call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string

The identity campaign certification ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Permissions for entitlement certification item Deprecated

This API returns the permissions associated with an entitlement certification item based on the certification item's ID. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. 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

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: ?filters=rights+ca+(%22CREATE%22)+and+rights+ca+(%SELECT%22)

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 Deprecated

This API returns a list of reviewers for the certification. A token with ORG_ADMIN or CERT_ADMIN authority is required to call this API. 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
[
  • {
    }
]

Certifications by ids Deprecated

This API returns a list of certifications that satisfy the given 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-identitiy
string

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

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

phase: eq

completed: eq, ne

campaignRef.campaignType: eq, in

campaignRef.id: eq, in

sorters
string <comma-separated>

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
[
  • {
    }
]

Connector Rule Management

Use this API to implement connector rule management functionality. With this functionality in place, administrators can implement connector-executed rules in a programmatic, scalable way.

In Identity Security Cloud (ISC), rules serve as a flexible configuration framework you can leverage to perform complex or advanced configurations. Connector-executed rules are rules that are executed in the ISC virtual appliance (VA), usually extensions of the connector itself, the bridge between the data source and ISC. This API allows administrators to view existing connector-executed rules, make changes to them, delete them, and create new ones from the available types.

List connector rules

Returns the list of connector rules. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create connector rule

Creates a new connector rule. A token with ORG_ADMIN authority is required to call this API.

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

The connector rule to create

name
required
string [ 1 .. 128 ] characters

the name of the rule

description
string

a description of the rule's purpose

type
required
string
Enum: "BuildMap" "ConnectorAfterCreate" "ConnectorAfterDelete" "ConnectorAfterModify" "ConnectorBeforeCreate" "ConnectorBeforeDelete" "ConnectorBeforeModify" "JDBCBuildMap" "JDBCOperationProvisioning" "JDBCProvision" "PeopleSoftHRMSBuildMap" "PeopleSoftHRMSOperationProvisioning" "PeopleSoftHRMSProvision" "RACFPermissionCustomization" "SAPBuildMap" "SapHrManagerRule" "SapHrOperationProvisioning" "SapHrProvision" "SuccessFactorsOperationProvisioning" "WebServiceAfterOperationRule" "WebServiceBeforeOperationRule" "ResourceObjectCustomization"

the type of rule

object

The rule's function signature. Describes the rule's input arguments and output (if any)

required
object (Source Code)

SourceCode

attributes
object or null

a map of string to objects

Responses

Request samples

Content type
application/json
{
  • "name": "WebServiceBeforeOperationRule",
  • "description": "This rule does that",
  • "type": "BuildMap",
  • "signature": {
    },
  • "sourceCode": {
    },
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "name": "WebServiceBeforeOperationRule",
  • "description": "This rule does that",
  • "type": "BuildMap",
  • "signature": {
    },
  • "sourceCode": {
    },
  • "attributes": { },
  • "id": "8113d48c0b914f17b4c6072d4dcb9dfe",
  • "created": "021-07-22T15:59:23Z",
  • "modified": "021-07-22T15:59:23Z"
}

Connector-rule by id

Returns the connector rule specified by ID. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 8c190e6787aa4ed9a90bd9d5344523fb

ID of the connector rule to retrieve

Responses

Response samples

Content type
application/json
{
  • "name": "WebServiceBeforeOperationRule",
  • "description": "This rule does that",
  • "type": "BuildMap",
  • "signature": {
    },
  • "sourceCode": {
    },
  • "attributes": { },
  • "id": "8113d48c0b914f17b4c6072d4dcb9dfe",
  • "created": "021-07-22T15:59:23Z",
  • "modified": "021-07-22T15:59:23Z"
}

Update a connector rule

Updates an existing connector rule with the one provided in the request body. Note that the fields 'id', 'name', and 'type' are immutable. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 8c190e6787aa4ed9a90bd9d5344523fb

ID of the connector rule to update

Request Body schema: application/json

The connector rule with updated data

id
required
string

the ID of the rule to update

name
required
string [ 1 .. 128 ] characters

the name of the rule

description
string

a description of the rule's purpose

type
required
string
Enum: "BuildMap" "ConnectorAfterCreate" "ConnectorAfterDelete" "ConnectorAfterModify" "ConnectorBeforeCreate" "ConnectorBeforeDelete" "ConnectorBeforeModify" "JDBCBuildMap" "JDBCOperationProvisioning" "JDBCProvision" "PeopleSoftHRMSBuildMap" "PeopleSoftHRMSOperationProvisioning" "PeopleSoftHRMSProvision" "RACFPermissionCustomization" "SAPBuildMap" "SapHrManagerRule" "SapHrOperationProvisioning" "SapHrProvision" "SuccessFactorsOperationProvisioning" "WebServiceAfterOperationRule" "WebServiceBeforeOperationRule" "ResourceObjectCustomization"

the type of rule

object

The rule's function signature. Describes the rule's input arguments and output (if any)

required
object (Source Code)

SourceCode

attributes
object or null

a map of string to objects

Responses

Request samples

Content type
application/json
{
  • "id": "8113d48c0b914f17b4c6072d4dcb9dfe",
  • "name": "WebServiceBeforeOperationRule",
  • "description": "This rule does that",
  • "type": "BuildMap",
  • "signature": {
    },
  • "sourceCode": {
    },
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "name": "WebServiceBeforeOperationRule",
  • "description": "This rule does that",
  • "type": "BuildMap",
  • "signature": {
    },
  • "sourceCode": {
    },
  • "attributes": { },
  • "id": "8113d48c0b914f17b4c6072d4dcb9dfe",
  • "created": "021-07-22T15:59:23Z",
  • "modified": "021-07-22T15:59:23Z"
}

Delete a connector-rule

Deletes the connector rule specified by the given ID. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
id
required
string
Example: 8c190e6787aa4ed9a90bd9d5344523fb

ID of the connector rule to delete

Responses

Response samples

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

Validate connector rule

Returns a list of issues within the code to fix, if any. A token with ORG_ADMIN authority is required to call this API.

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

The code to validate

version
required
string

the version of the code

script
required
string

The code

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "script": "return \"Mr. \" + firstName;"
}

Response samples

Content type
application/json
{
  • "state": "ERROR",
  • "details": [
    ]
}

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 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

type: eq

directConnect: eq

category: eq

features: 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
[
  • {
    }
]

Custom Forms

Use this API to build and manage custom forms. With this functionality in place, administrators can create and view form definitions and form instances.

Forms are composed of sections and fields. Sections split the form into logical groups of fields and fields are the data collection points within the form. Configure conditions to modify elements of the form as the responder provides input. Create form inputs to pass information from a calling feature, like a workflow, to your form.

Forms can be used within workflows as an action or as a trigger. The Form Action allows you to assign a form as a step in a running workflow, suspending the workflow until the form is submitted or times out, and the workflow resumes. The Form Submitted Trigger initiates a workflow when a form is submitted. The trigger can be configured to initiate on submission of a full form, a form element with any value, or a form element with a particular value.

Refer to Forms for more information about using forms in Identity Security Cloud.

Export form definitions by tenant.

No parameters required.

Authorizations:
Personal Access Token
query Parameters
offset
integer <int64>
Default: 0
Example: offset=250

Offset

Integer specifying the offset of the first result from the beginning of the collection. The standard syntax described in V3 API Standard Collection Parameters. The offset value is record-based, not page-based, and the index starts at 0.

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

Limit

Integer specifying the maximum number of records to return in a single API call. The standard syntax described in V3 API Standard Collection Parameters. If it is not specified, a default limit is used.

filters
string
Example: filters=name sw "my form"

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

Filtering is supported for the following fields and operators:

name: eq, gt, sw, in

description: eq, gt, sw, in

created: eq, gt, sw, in

modified: eq, gt, sw, in

sorters
string
Default: "name"
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, created, modified

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "results": [
    ]
}

Creates a form definition.

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

Body is the request payload to create form definition request

description
string [ 0 .. 2000 ] characters

Description is the form definition description

Array of objects (FormCondition)

FormConditions is the conditional logic that modify the form dynamically modify the form as the recipient is interacting out the form

Array of objects (FormElement)

FormElements is a list of nested form elements

Array of objects (FormDefinitionInput)

FormInput is a list of form inputs that are required when creating a form-instance object

name
required
string <= 255 characters

Name is the form definition name

required
object (FormOwner)
Array of objects (FormUsedBy)

UsedBy is a list of objects where when any system uses a particular form it reaches out to the form service to record it is currently being used

Responses

Request samples

Content type
application/json
{
  • "name": "my form",
  • "description": "my form description",
  • "owner": {
    },
  • "formElements": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "My form",
  • "description": "My form description",
  • "owner": {
    },
  • "usedBy": [
    ],
  • "formInput": [
    ],
  • "formElements": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z"
}

Return a form definition.

Parameter {formDefinitionID} should match a form definition ID.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form definition ID

Responses

Response samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "My form",
  • "description": "My form description",
  • "owner": {
    },
  • "usedBy": [
    ],
  • "formInput": [
    ],
  • "formElements": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z"
}

Deletes a form definition.

Parameter {formDefinitionID} should match a form definition ID.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form definition ID

Responses

Response samples

Content type
application/json
{ }

Patch a form definition.

Parameter {formDefinitionID} should match a form definition ID.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form definition ID

Request Body schema: application/json

Body is the request payload to patch a form definition, check: https://jsonpatch.com

Array
property name*
additional property
object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "My form",
  • "description": "My form description",
  • "owner": {
    },
  • "usedBy": [
    ],
  • "formInput": [
    ],
  • "formElements": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z"
}

Preview form definition data source.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form definition ID

query Parameters
limit
integer <int64> [ 0 .. 250 ] characters
Default: 10
Example: limit=10

Limit

Integer specifying the maximum number of records to return in a single API call. The standard syntax described in V3 API Standard Collection Parameters. If it is not specified, a default limit is used.

filters
string
Example: filters=value eq "ID01"

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

Filtering is supported for the following fields and operators:

value: eq, ne, in

Supported composite operators: not

Only a single not may be used, and it can only be used with the in operator. The not composite operator must be used in front of the field. For example, the following is valid: not value in ("ID01")

query
string
Example: query=ac

String that is passed to the underlying API to filter other (non-ID) fields. For example, for access profile data sources, this string will be passed to the access profile api and used with a "starts with" filter against several fields.

Request Body schema: application/json

Body is the request payload to create a form definition dynamic schema

object (FormElementDynamicDataSource)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "results": "{\"results\":[{\"label\":\"Alfred 255e71dfc6e\",\"subLabel\":\"Alfred.255e71dfc6e@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e16676\"},{\"label\":\"Alize eba9d4cd27da\",\"subLabel\":\"Alize.eba9d4cd27da@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2f1667c\"},{\"label\":\"Antonina 01f69c3ea\",\"subLabel\":\"Antonina.01f69c3ea@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2f9667e\"},{\"label\":\"Ardella 21e78ce155\",\"subLabel\":\"Ardella.21e78ce155@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e6667a\"},{\"label\":\"Arnaldo d8582b6e17\",\"subLabel\":\"Arnaldo.d8582b6e17@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced3426686\"},{\"label\":\"Aurelia admin24828\",\"subLabel\":\"Aurelia.admin24828@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e16674\"},{\"label\":\"Barbara 72ca418fdd\",\"subLabel\":\"Barbara.72ca418fdd@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2fb6680\"},{\"label\":\"Barbara ee1a2436ee\",\"subLabel\":\"Barbara.ee1a2436ee@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e56678\"},{\"label\":\"Baylee 652d72432f3\",\"subLabel\":\"Baylee.652d72432f3@testmail.identitysoon.com\",\"value\":\"2c91808582184782018227ced28b6aee\"},{\"label\":\"Brock e76b56ae4d49\",\"subLabel\":\"Brock.e76b56ae4d49@testmail.identitysoon.com\",\"value\":\"2c91808582184782018227ced28b6aef\"}]}"
}

List form definitions by tenant.

No parameters required.

Authorizations:
Personal Access Token
query Parameters
offset
integer <int64>
Default: 0

Offset

Integer specifying the offset of the first result from the beginning of the collection. The standard syntax described in V3 API Standard Collection Parameters. The offset value is record-based, not page-based, and the index starts at 0.

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

Limit

Integer specifying the maximum number of records to return in a single API call. The standard syntax described in V3 API Standard Collection Parameters. If it is not specified, a default limit is used.

filters
string
Example: filters=name sw "my form"

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

Filtering is supported for the following fields and operators:

name: eq, gt, sw, in

description: eq, gt, sw, in

created: eq, gt, sw, in

modified: eq, gt, sw, in

sorters
string
Default: "name"
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, created, modified

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate json schema dynamically.

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

Body is the request payload to create a form definition dynamic schema

object
description
string

Description is the form definition dynamic schema description text

id
string

ID is a unique identifier

type
string

Type is the form definition dynamic schema type

versionNumber
integer <int64>

VersionNumber is the form definition dynamic schema version number

Responses

Request samples

Content type
application/json
{
  • "id": "sp:forms",
  • "attributes": {
    },
  • "description": "AnotherDescription",
  • "type": "action",
  • "versionNumber": 1
}

Response samples

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

Import form definitions from export.

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

Body is the request payload to import form definitions

Array
object (FormDefinitionResponse)
self
string
version
integer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "importedObjects": [
    ],
  • "infos": [
    ],
  • "warnings": [
    ]
}

Create a form definition by template.

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

Body is the request payload to create form definition request

description
string [ 0 .. 2000 ] characters

Description is the form definition description

Array of objects (FormCondition)

FormConditions is the conditional logic that modify the form dynamically modify the form as the recipient is interacting out the form

Array of objects (FormElement)

FormElements is a list of nested form elements

Array of objects (FormDefinitionInput)

FormInput is a list of form inputs that are required when creating a form-instance object

name
required
string <= 255 characters

Name is the form definition name

required
object (FormOwner)
Array of objects (FormUsedBy)

UsedBy is a list of objects where when any system uses a particular form it reaches out to the form service to record it is currently being used

Responses

Request samples

Content type
application/json
{
  • "name": "my form",
  • "description": "my form description",
  • "owner": {
    },
  • "formElements": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "My form",
  • "description": "My form description",
  • "owner": {
    },
  • "usedBy": [
    ],
  • "formInput": [
    ],
  • "formElements": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z"
}

Upload new form definition file.

Parameter {formDefinitionID} should match a form definition ID.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

FormDefinitionID

String specifying FormDefinitionID

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

File specifying the multipart

Responses

Response samples

Content type
application/json
{
  • "created": "2023-07-12T20:14:57.74486Z",
  • "fileId": "01FHZXHK8PTP9FVK99Z66GXQTX.png",
  • "formDefinitionId": "00000000-0000-0000-0000-000000000000"
}

Download definition file by fileid.

Authorizations:
Personal Access Token
path Parameters
formDefinitionID
required
string
Example: 00000000-0000-0000-0000-000000000000

FormDefinitionID

Form definition ID

fileID
required
string
Example: 00000031N0J7R2B57M8YG73J7M.png

FileID

String specifying the hashed name of the uploaded file we are retrieving.

Responses

Response samples

Content type
"string"

List form instances by tenant.

No parameters required.

Authorizations:
Personal Access Token
query Parameters
offset
integer <int64>
Default: 0

Offset

Integer specifying the offset of the first result from the beginning of the collection. The standard syntax described in V3 API Standard Collection Parameters. The offset value is record-based, not page-based, and the index starts at 0.

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

Limit

Integer specifying the maximum number of records to return in a single API call. The standard syntax described in V3 API Standard Collection Parameters. If it is not specified, a default limit is used.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a form instance.

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

Body is the request payload to create a form instance

required
object (FormInstanceCreatedBy)
expire
required
string

Expire is required

formDefinitionId
required
string

FormDefinitionID is the id of the form definition that created this form

object

FormInput is an object of form input labels to value

required
Array of objects (FormInstanceRecipient)

Recipients is required

standAloneForm
boolean
Default: false

StandAloneForm is a boolean flag to indicate if this form should be available for users to complete via the standalone form UI or should this only be available to be completed by as an embedded form

state
string
Enum: "ASSIGNED" "IN_PROGRESS" "SUBMITTED" "COMPLETED" "CANCELLED"

State is required, if not present initial state is FormInstanceStateAssigned ASSIGNED FormInstanceStateAssigned IN_PROGRESS FormInstanceStateInProgress SUBMITTED FormInstanceStateSubmitted COMPLETED FormInstanceStateCompleted CANCELLED FormInstanceStateCancelled

ttl
integer <int64>

TTL an epoch timestamp in seconds, it most be in seconds or dynamodb will ignore it SEE: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-before-you-start.html

Responses

Request samples

Content type
application/json
{
  • "expire": "2023-06-20T15:57:55.332882Z",
  • "formDefinitionId": "00000000-0000-0000-0000-000000000000",
  • "recipients": [
    ],
  • "createdBy": {
    }
}

Response samples

Content type
application/json
{
  • "id": "06a2d961-07fa-44d1-8d0a-2f6470e30fd2",
  • "expire": "2023-08-12T20:14:57.74486Z",
  • "state": "ASSIGNED",
  • "standAloneForm": false,
  • "standAloneFormUrl": "https://my-org.identitynow.com/ui/d/forms/00000000-0000-0000-0000-000000000000",
  • "createdBy": {
    },
  • "formDefinitionId": "49841cb8-00a5-4fbd-9888-8bbb28d48331",
  • "formInput": {
    },
  • "formElements": [
    ],
  • "formData": {
    },
  • "formErrors": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z",
  • "recipients": [
    ]
}

Returns a form instance.

Parameter {formInstanceID} should match a form instance ID.

Only the assigned recipient (recipients[].id when type is IDENTITY) may call this.

Authorizations:
Personal Access Token
path Parameters
formInstanceID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form instance ID

Responses

Response samples

Content type
application/json
{
  • "id": "06a2d961-07fa-44d1-8d0a-2f6470e30fd2",
  • "expire": "2023-08-12T20:14:57.74486Z",
  • "state": "ASSIGNED",
  • "standAloneForm": false,
  • "standAloneFormUrl": "https://my-org.identitynow.com/ui/d/forms/00000000-0000-0000-0000-000000000000",
  • "createdBy": {
    },
  • "formDefinitionId": "49841cb8-00a5-4fbd-9888-8bbb28d48331",
  • "formInput": {
    },
  • "formElements": [
    ],
  • "formData": {
    },
  • "formErrors": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z",
  • "recipients": [
    ]
}

Patch a form instance.

Parameter {formInstanceID} should match a form instance ID.

Only the assigned recipient (recipients[].id when type is IDENTITY) may call this.

Authorizations:
Personal Access Token
path Parameters
formInstanceID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form instance ID

Request Body schema: application/json

Body is the request payload to patch a form instance, check: https://jsonpatch.com

Array
property name*
additional property
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "06a2d961-07fa-44d1-8d0a-2f6470e30fd2",
  • "expire": "2023-08-12T20:14:57.74486Z",
  • "state": "ASSIGNED",
  • "standAloneForm": false,
  • "standAloneFormUrl": "https://my-org.identitynow.com/ui/d/forms/00000000-0000-0000-0000-000000000000",
  • "createdBy": {
    },
  • "formDefinitionId": "49841cb8-00a5-4fbd-9888-8bbb28d48331",
  • "formInput": {
    },
  • "formElements": [
    ],
  • "formData": {
    },
  • "formErrors": [
    ],
  • "formConditions": [
    ],
  • "created": "2023-07-12T20:14:57.74486Z",
  • "modified": "2023-07-12T20:14:57.74486Z",
  • "recipients": [
    ]
}

Retrieves dynamic data by element.

Parameter {formInstanceID} should match a form instance ID. Parameter {formElementID} should match a form element ID at the data source configuration.

Authorizations:
Personal Access Token
path Parameters
formInstanceID
required
string
Example: 00000000-0000-0000-0000-000000000000

Form instance ID

formElementID
required
string
Example: 1

Form element ID

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

Limit

Integer specifying the maximum number of records to return in a single API call. The standard syntax described in V3 API Standard Collection Parameters. If it is not specified, a default limit is used.

filters
string
Example: filters=value eq "ID01"

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

Filtering is supported for the following fields and operators:

value: eq, ne, in

Supported composite operators: not

Only a single not may be used, and it can only be used with the in operator. The not composite operator must be used in front of the field. For example, the following is valid: not value in ("ID01")

query
string
Example: query=support

String that is passed to the underlying API to filter other (non-ID) fields. For example, for access profile data sources, this string will be passed to the access profile api and used with a "starts with" filter against several fields.

Responses

Response samples

Content type
application/json
{
  • "results": "{\"results\":[{\"label\":\"Alfred 255e71dfc6e\",\"subLabel\":\"Alfred.255e71dfc6e@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e16676\"},{\"label\":\"Alize eba9d4cd27da\",\"subLabel\":\"Alize.eba9d4cd27da@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2f1667c\"},{\"label\":\"Antonina 01f69c3ea\",\"subLabel\":\"Antonina.01f69c3ea@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2f9667e\"},{\"label\":\"Ardella 21e78ce155\",\"subLabel\":\"Ardella.21e78ce155@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e6667a\"},{\"label\":\"Arnaldo d8582b6e17\",\"subLabel\":\"Arnaldo.d8582b6e17@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced3426686\"},{\"label\":\"Aurelia admin24828\",\"subLabel\":\"Aurelia.admin24828@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e16674\"},{\"label\":\"Barbara 72ca418fdd\",\"subLabel\":\"Barbara.72ca418fdd@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2fb6680\"},{\"label\":\"Barbara ee1a2436ee\",\"subLabel\":\"Barbara.ee1a2436ee@testmail.identitysoon.com\",\"value\":\"2c918084821847c5018227ced2e56678\"},{\"label\":\"Baylee 652d72432f3\",\"subLabel\":\"Baylee.652d72432f3@testmail.identitysoon.com\",\"value\":\"2c91808582184782018227ced28b6aee\"},{\"label\":\"Brock e76b56ae4d49\",\"subLabel\":\"Brock.e76b56ae4d49@testmail.identitysoon.com\",\"value\":\"2c91808582184782018227ced28b6aef\"}]}"
}

Download instance file by fileid.

Authorizations:
Personal Access Token
path Parameters
formInstanceID
required
string
Example: 00000000-0000-0000-0000-000000000000

FormInstanceID

Form instance ID

fileID
required
string
Example: 00000031N0J7R2B57M8YG73J7M.png

FileID

String specifying the hashed name of the uploaded file we are retrieving.

Responses

Response samples

Content type
"string"

List predefined select options.

No parameters required.

Authorizations:
Personal Access Token

Responses

Response samples

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

Custom Password Instructions

Use this API to implement custom password instruction functionality. With this functionality in place, administrators can create custom password instructions to help users reset their passwords, change them, unlock their accounts, or recover their usernames. This allows administrators to emphasize password policies or provide organization-specific instructions.

Administrators must first use Update Password Org Config to set customInstructionsEnabled to true.

Once they have enabled custom instructions, they can use Create Custom Password Instructions to create custom page content for the specific pageId they select.

For example, an administrator can use the pageId forget-username:user-email to set the custom text for the case when users forget their usernames and must enter their emails.

Refer to Creating Custom Instruction Text for more information about creating custom password instructions.

Create custom password instructions

This API creates the custom password instructions for the specified page ID. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
Request Body schema: application/json
pageId
string
Enum: "change-password:enter-password" "change-password:finish" "flow-selection:select" "forget-username:user-email" "mfa:enter-code" "mfa:enter-kba" "mfa:select" "reset-password:enter-password" "reset-password:enter-username" "reset-password:finish" "unlock-account:enter-username" "unlock-account:finish"

The page ID that represents the page for forget user name, reset password and unlock account flow.

pageContent
string

The custom instructions for the specified page. Allow basic HTML format and maximum length is 1000 characters. The custom instructions will be sanitized to avoid attacks. If the customization text includes a link, like <A HREF=\"URL\">...</A> clicking on this will open the link on the current browser page. If you want your link to be redirected to a different page, please redirect it to "_blank" like this: <a href=\"URL" target=\"_blank\" >link</a>. This will open a new tab when the link is clicked. Notice we're only supporting _blank as the redirection target.

locale
string

The locale for the custom instructions, a BCP47 language tag. The default value is "default".

Responses

Request samples

Content type
application/json
{
  • "pageId": "reset-password:enter-password",
  • "pageContent": "See company password policies for details by clicking <a href=\"url\">here</a>"
}

Response samples

Content type
application/json
{
  • "pageId": "reset-password:enter-password",
  • "locale": "default",
  • "pageContent": "See company password policies for details by clicking <a href=\"url\">here</a>"
}

Get custom password instructions by page id

This API returns the custom password instructions for the specified page ID. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
pageId
required
string
Enum: "change-password:enter-password" "change-password:finish" "flow-selection:select" "forget-username:user-email" "mfa:enter-code" "mfa:enter-kba" "mfa:select" "reset-password:enter-password" "reset-password:enter-username" "reset-password:finish" "unlock-account:enter-username" "unlock-account:finish"
Example: mfa:select

The page ID of custom password instructions to query.

query Parameters
locale
string

The locale for the custom instructions, a BCP47 language tag. The default value is "default".

Responses

Response samples

Content type
application/json
{
  • "pageId": "reset-password:enter-password",
  • "locale": "default",
  • "pageContent": "See company password policies for details by clicking <a href=\"url\">here</a>"
}

Delete custom password instructions by page id

This API delete the custom password instructions for the specified page ID. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
pageId
required
string
Enum: "change-password:enter-password" "change-password:finish" "flow-selection:select" "forget-username:user-email" "mfa:enter-code" "mfa:enter-kba" "mfa:select" "reset-password:enter-password" "reset-password:enter-username" "reset-password:finish" "unlock-account:enter-username" "unlock-account:finish"
Example: mfa:select

The page ID of custom password instructions to delete.

query Parameters
locale
string

The locale for the custom instructions, a BCP47 language tag. The default value is "default".

Responses

Response samples

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

Entitlements

Use this API to implement and customize entitlement functionality. With this functionality in place, administrators can view entitlements and configure them for use throughout Identity Security Cloud in certifications, access profiles, and roles. Administrators in Identity Security Cloud can then grant users access to the entitlements or configure them so users themselves can request access to the entitlements whenever they need them. With a good approval process, this entitlement functionality allows users to gain the specific access they need on sources quickly and securely.

Entitlements represent access rights on sources. Entitlements are the most granular form of access in Identity Security Cloud. Entitlements are often grouped into access profiles, and access profiles themselves are often grouped into roles, the broadest form of access in Identity Security Cloud.

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.

Administrators often use roles and access profiles within those roles to manage access so that users can gain access more quickly, but the hierarchy of access all starts with entitlements.

Anywhere entitlements appear, you can select them to find more information about the following:

  • Cloud Access Details: These provide details about the cloud access entitlements on cloud-enabled sources.

  • Permissions: Permissions represent individual units of read/write/admin access to a system.

  • Relationships: These list each entitlement's parent and child relationships.

  • Type: This is the entitlement's type. Some sources support multiple types, each with a different attribute schema.

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

  • Certifications: Entitlements can be revoked from an identity that no longer needs them.

  • Roles: Roles can group access profiles which themselves group entitlements. You can grant and revoke access on a broad level with roles. Role membership criteria can grant roles to identities based on whether they have certain entitlements or attributes.

  • Access Profiles: Access profiles group entitlements. They are the most important units of access in Identity Security Cloud. Identity Security Cloud uses them in provisioning, certifications, and access requests, and administrators can configure them to grant very broad or very granular access.

You cannot delete entitlements directly from Identity Security Cloud. Entitlements are deleted based on their inclusion in aggregations.

Refer to Deleting Entitlements more information about deleting entitlements.

Refer to Entitlements for more information about entitlements.

Gets a list of entitlements.

This API returns a list of entitlements.

This API can be used in one of the two following ways: either getting entitlements for a specific account-id, or getting via use of filters (those two options are exclusive).

Any authenticated token can call this API.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
account-id
string
Deprecated
Example: account-id=ef38f94347e94562b5bb8424a56397d8

The account ID. If specified, returns only entitlements associated with the given Account. Cannot be specified with the filters, segmented-for-identity, for-segment-ids, or include-unsegmented param(s). This parameter is deprecated. Please use Account Entitlements API to get account entitlements.

segmented-for-identity
string
Example: segmented-for-identity=e554098913544630b5985e9042f5e44b

If present and not empty, additionally filters Entitlements to those which are assigned to the Segment(s) which are visible to the Identity with the specified ID. Cannot be specified with the account-id or for-segment-ids param(s). It is also illegal to specify a value that refers to a different user's Identity.

for-segment-ids
string <comma-separated>
Example: for-segment-ids=041727d4-7d95-4779-b891-93cf41e98249,a378c9fa-bae5-494c-804e-a1e30f69f649

If present and not empty, additionally filters Access Profiles to those which are assigned to the Segment(s) with the specified IDs. Cannot be specified with the account-id or segmented-for-identity param(s).

include-unsegmented
boolean
Default: true
Example: include-unsegmented=true

Whether or not the response list should contain unsegmented Entitlements. If for-segment-ids and segmented-for-identity are both absent or empty, specifying include-unsegmented=false results in an error.

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.

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: id, name, created, modified, type, attribute, value, source.id, requestable

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, in, sw

type: eq, in

attribute: eq, in

value: eq, in, sw

source.id: eq, in

requestable: eq

created: gt, lt, ge, le

modified: gt, lt, ge, le

owner.id: eq, in

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an entitlement

This API returns an entitlement by its ID.

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

The entitlement ID

Responses

Response samples

Content type
application/json
{
  • "sourceSchemaObjectType": "group",
  • "attribute": "memberOf",
  • "attributes": {
    },
  • "value": "CN=PayrollControls,OU=Groups,OU=Demo,DC=seri,DC=sailpointdemo,DC=com",
  • "description": "Grants the ability to access and manage payroll-related controls and settings within the Corporate Active Directory system.",
  • "privileged": false,
  • "cloudGoverned": false,
  • "source": {
    },
  • "owner": {
    },
  • "segments": [
    ],
  • "manuallyUpdatedFields": {
    },
  • "id": "2c91808c74ff913f0175097daa9d59cd",
  • "name": "PayrollControls",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2021-01-19T16:53:35.707Z"
}

Patch an entitlement

This API updates an existing entitlement using JSON Patch syntax.

The following fields are patchable: requestable, privileged, segments, owner, name, description and manuallyUpdatedFields

When you're patching owner, only owner type and owner id must be provided. Owner name is optional, and it won't be modified. If the owner name is provided, it should correspond to the real name. The only owner type currently supported is IDENTITY.

A token with ORG_ADMIN or SOURCE_ADMIN authority is required to call this API.

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

ID of the entitlement 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": "2c91808874ff91550175097daaec161c",
  • "name": "LauncherTest2",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "attribute": "memberOf",
  • "value": "CN=LauncherTest2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local",
  • "sourceSchemaObjectType": "group",
  • "privileged": true,
  • "cloudGoverned": true,
  • "description": "CN=LauncherTest2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local",
  • "requestable": true,
  • "attributes": {
    },
  • "source": {
    },
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "directPermissions": [
    ],
  • "segments": [
    ],
  • "manuallyUpdatedFields": {
    },
  • "accessModelMetadata": {
    }
}

List of entitlements parents

This API returns a list of all parent entitlements of a given entitlement.

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

Entitlement 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=name,-modified

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

Sorting is supported for the following fields: id, name, created, modified, type, attribute, value, source.id

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, in, sw

type: eq, in

attribute: eq, in

value: eq, in, sw

source.id: eq, in

requestable: eq

created: gt, lt, ge, le

modified: gt, lt, ge, le

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List of entitlements children

This API returns a list of all child entitlements of a given entitlement.

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

Entitlement 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=name,-modified

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

Sorting is supported for the following fields: id, name, created, modified, type, attribute, value, source.id

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, in, sw

type: eq, in

attribute: eq, in

value: eq, in, sw

source.id: eq, in

requestable: eq

created: gt, lt, ge, le

modified: gt, lt, ge, le

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bulk update an entitlement list

This API applies an update to every entitlement of the list.

The number of entitlements to update is limited to 50 items maximum.

The JsonPatch update follows the JSON Patch standard. examples of allowed operations : **{ "op": "replace", "path": "/privileged", "value": boolean }** **{ "op": "replace", "path": "/requestable","value": boolean }**

A token with ORG_ADMIN or API authority is required to call this API.

Authorizations:
Personal Access Token
Request Body schema: application/json
entitlementIds
required
Array of strings <= 50 items

List of entitlement ids to update

required
Array of objects (Json Patch Operation)

List of entitlement ids to update

Responses

Request samples

Content type
application/json
{
  • "entitlementIds": [
    ],
  • "jsonPatch": [
    ]
}

Response samples

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

Get entitlement request config

This API returns the entitlement request config for a specified entitlement.

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

Entitlement Id

Responses

Response samples

Content type
application/json
{
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    }
}

Replace entitlement request config

This API replaces the entitlement request config for a specified entitlement.

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

Entitlement ID

Request Body schema: application/json
object (Entitlement Access Request Config)
object (Entitlement Revocation Request Config)

Responses

Request samples

Content type
application/json
{
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    }
}

Response samples

Content type
application/json
{
  • "accessRequestConfig": {
    },
  • "revocationRequestConfig": {
    }
}

Reset source entitlements

Remove all entitlements from a specific source. To reload the accounts along with the entitlements you removed, you must run an unoptimized aggregation. To do so, use Import Accounts with disableOptimization = true.

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

ID of source for the entitlement reset

Responses

Response samples

Content type
application/json
{
  • "type": "TASK_RESULT",
  • "id": "2c91808568c529c60168cca6f90c1313",
  • "name": "Entitlement Source Reset"
}

Add metadata to an entitlement.

Add single Access Model Metadata to an entitlement.

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

The entitlement id.

attributeKey
required
string
Example: iscPrivacy

Technical name of the Attribute.

attributeValue
required
string
Example: public

Technical name of the Attribute Value.

Responses

Response samples

Content type
application/json
{
  • "id": "2c91808874ff91550175097daaec161c",
  • "name": "LauncherTest2",
  • "created": "2020-10-08T18:33:52.029Z",
  • "modified": "2020-10-08T18:33:52.029Z",
  • "attribute": "memberOf",
  • "value": "CN=LauncherTest2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local",
  • "sourceSchemaObjectType": "group",
  • "privileged": true,
  • "cloudGoverned": true,
  • "description": "CN=LauncherTest2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local",
  • "requestable": true,
  • "attributes": {
    },
  • "source": {
    },
  • "owner": {
    },
  • "additionalOwners": [
    ],
  • "directPermissions": [
    ],
  • "segments": [
    ],
  • "manuallyUpdatedFields": {
    },
  • "accessModelMetadata": {
    }
}

Remove metadata from an entitlement.

Remove single Access Model Metadata from an entitlement.

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

The entitlement id.

attributeKey
required
string
Example: iscPrivacy

Technical name of the Attribute.

attributeValue
required
string
Example: public

Technical name of the Attribute Value.

Responses

Response samples

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

Aggregate entitlements Deprecated

Starts an entitlement aggregation on the specified source. Though this endpoint has been deprecated, you can find its Beta equivalent here.

If the target source is a direct connection, then the request body must be empty. You will also need to make sure the Content-Type header is not set. If you set the Content-Type header without specifying a body, then you will receive a 500 error.

If the target source is a delimited file source, then the CSV file needs to be included in the request body. You will also need to set the Content-Type header to multipart/form-data.

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

Source Id

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

The CSV file containing the source entitlements to aggregate.

Responses

Response samples

Content type
application/json
{
  • "id": "ef38f94347e94562b5bb8424a56397d8",
  • "type": "QUARTZ",
  • "uniqueName": "Cloud Group Aggregation",
  • "description": "Aggregate from the specified application",
  • "launcher": "John Doe",
  • "created": "2020-07-11T21:23:15.000Z",
  • "returns": [
    ]
}

Governance Groups

Use this API to implement and customize Governance Group functionality. With this functionality in place, administrators can create Governance Groups and configure them for use throughout Identity Security Cloud.

A governance group is a group of users that can make governance decisions about access. If your organization has the Access Request or Certifications service, you can configure governance groups to review access requests or certifications. A governance group can determine whether specific access is appropriate for a user.

Refer to Creating and Managing Governance Groups for more information about how to build Governance Groups in the visual builder in the Identity Security Cloud UI.

List governance groups

This API returns list of Governance Groups

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 sw "Test"

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

name: eq, sw, in

memberships.identityId: eq, in

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, id, description

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new governance group.

This API creates a new Governance Group.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
object (Owner Dto)

Owner's identity.

name
string

Governance group name.

description
string

Governance group description.

created
string <date-time>
modified
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "owner": {
    },
  • "name": "DB Access Governance Group",
  • "description": "Description of the Governance Group",
  • "created": "2022-01-06T19:51:13Z",
  • "modified": "2022-01-06T19:51:13Z"
}

Response samples

Content type
application/json
{
  • "owner": {
    },
  • "id": "2c91808568c529c60168cca6f90c1313",
  • "name": "DB Access Governance Group",
  • "description": "Description of the Governance Group",
  • "memberCount": 1641498673000,
  • "connectionCount": 1641498673000,
  • "created": "2022-01-06T19:51:13Z",
  • "modified": "2022-01-06T19:51:13Z"
}

Get governance group by id

This API returns a Governance Groups by its ID.

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

ID of the Governance Group

Responses

Response samples

Content type
application/json
{
  • "owner": {
    },
  • "id": "2c91808568c529c60168cca6f90c1313",
  • "name": "DB Access Governance Group",
  • "description": "Description of the Governance Group",
  • "memberCount": 1641498673000,
  • "connectionCount": 1641498673000,
  • "created": "2022-01-06T19:51:13Z",
  • "modified": "2022-01-06T19:51:13Z"
}

Delete a governance group

This API deletes a Governance Group by its ID.

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

ID of the Governance Group

Responses

Response samples

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

Patch a governance group

This API updates an existing governance group by ID. The following fields and objects are patchable:

  • name
  • description
  • owner

A token with API or ORG_ADMIN authority is required to call this API.

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

ID of the Governance Group

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

Replace description of a Governance Group.

[
  • {
    }
]

Response samples

Content type
application/json
{
  • "owner": {
    },
  • "id": "2c91808568c529c60168cca6f90c1313",
  • "name": "DB Access Governance Group",
  • "description": "Description of the Governance Group",
  • "memberCount": 1641498673000,
  • "connectionCount": 1641498673000,
  • "created": "2022-01-06T19:51:13Z",
  • "modified": "2022-01-06T19:51:13Z"
}

Delete governance group(s)

This API initiates a bulk deletion of one or more Governance Groups.

If any of the indicated Governance Groups have one or more connections associated with it,then those Governance Groups will be added in inUse list of the response. Governance Group(s) marked as inUse can not be deleted.

If any of the indicated Governance Groups is not does not exists in Organization,then those Governance Groups will be added in notFound list of the response. Governance Groups marked as notFound will not be deleted.

If any of the indicated Governance Groups does not have any connections associated with it,then those Governance Groups will be added in deleted list of the response. A Governance Group marked as deleted will be deleted from current Organization.

If the request contains any inUse or notFound Governance Group IDs then it skips only these Governance Groups for deletion and deletes the rest of Governance Groups which have no connections associated with it.

This API has limit number of Governance Groups can be deleted at one time. If the request contains more then 100 Governance Groups IDs to be deleted then the API will throw an exception.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
ids
Array of strings

List of IDs of Governance Groups to be deleted.

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

List connections for governance group

This API returns list of connections associated with a Governance Group.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
workgroupId
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the Governance Group.

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 .. 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.

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,-modified

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List governance group members

This API returns list of members associated with a Governance Group.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
workgroupId
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the Governance Group.

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 .. 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.

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,-modified

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add members to governance group

This API adds one or more members to a Governance Group. A token with API, ORG_ADMIN authority is required to call this API.

Following field of Identity is an optional field in the request.

name

Authorizations:
Personal Access TokenClient Credentials
path Parameters
workgroupId
required
string
Example: 2c91808a7813090a017814121919ecca

ID of the Governance Group.

Request Body schema: application/json

List of identities to be added to a Governance Group members list.

Array
type
string
Value: "IDENTITY"

Identity's DTO type.

id
string

Identity ID.

name
string

Identity's display name.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Remove members from governance group

This API removes one or more members from a Governance Group. A token with API, ORG_ADMIN authority is required to call this API.

Following field of Identity is an optional field in the request.

name

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

ID of the Governance Group.

Request Body schema: application/json

List of identities to be removed from a Governance Group members list.

Array
type
string
Value: "IDENTITY"

Identity's DTO type.

id
string

Identity ID.

name
string

Identity's display name.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

IAI Access Request Recommendations

Identity access request recommendations

This API returns the access request recommendations for the specified identity. The default identity is me which indicates the current user.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
identity-id
string
Default: "me"
Example: identity-id=2c91808570313110017040b06f344ec9

Get access request recommendations for an identityId. me indicates the current user.

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

Max number of results to return.

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.

include-translation-messages
boolean
Default: false

If true it will populate a list of translation messages in the response.

filters
string
Example: filters=access.name co "admin"

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

Filtering is supported for the following fields and operators:

access.name: co

access.type: eq, in

access.description: co, eq, in

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, access.type

By default the recommendations are sorted by highest confidence first.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Ignore access request recommendation

This API ignores a recommended access request item. Once an item is ignored, it will be marked as ignored=true if it is still a recommended item. The consumer can decide to hide ignored recommendations.

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

The recommended access item to ignore for an identity.

identityId
required
string <UUID>

The identity ID taking the action.

required
object (Access Request Recommendation Item)

Responses

Request samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    }
}

Response samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    },
  • "timestamp": "2017-07-11T18:45:37.098Z"
}

List ignored access request recommendations

This API returns the list of ignored access request recommendations.

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=identityId eq "2c9180846b0a0583016b299f210c1314"

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

Filtering is supported for the following fields and operators:

access.id: eq, in

access.type: eq, in

identityId: eq, in

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

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

Sorting is supported for the following fields: access.id, access.type, identityId, timestamp

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept access request recommendation

This API consumes a notification that a recommended access request item was requested. This API does not actually make the request, it is just a notification. This will help provide feedback in order to improve our recommendations.

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

The recommended access item that was requested for an identity.

identityId
required
string <UUID>

The identity ID taking the action.

required
object (Access Request Recommendation Item)

Responses

Request samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    }
}

Response samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    },
  • "timestamp": "2017-07-11T18:45:37.098Z"
}

List accepted access request recommendations

This API returns a list of requested access request recommendations.

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=access.id eq "2c9180846b0a0583016b299f210c1314"

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

Filtering is supported for the following fields and operators:

access.id: eq, in

access.type: eq, in

identityId: eq, in

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

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

Sorting is supported for the following fields: access.id, access.type, identityId, timestamp

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark viewed access request recommendations

This API consumes a notification that a recommended access request item was viewed. Future recommendations with this item will be marked with viewed=true. This can be useful for the consumer to determine if there are any new/unviewed recommendations.

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

The recommended access that was viewed for an identity.

identityId
required
string <UUID>

The identity ID taking the action.

required
object (Access Request Recommendation Item)

Responses

Request samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    }
}

Response samples

Content type
application/json
{
  • "identityId": "2c91808570313110017040b06f344ec9",
  • "access": {
    },
  • "timestamp": "2017-07-11T18:45:37.098Z"
}

List viewed access request recommendations

This API returns the list of viewed access request recommendations.

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=access.id eq "2c9180846b0a0583016b299f210c1314"

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

Filtering is supported for the following fields and operators:

access.id: eq, in

access.type: eq, in

identityId: eq, in

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

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

Sorting is supported for the following fields: access.id, access.type, identityId, timestamp

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bulk mark viewed access request recommendations

This API consumes a notification that a set of recommended access request item were viewed. Future recommendations with these items will be marked with viewed=true. This can be useful for the consumer to determine if there are any new/unviewed recommendations.

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

The recommended access items that were viewed for an identity.

Array
identityId
required
string <UUID>

The identity ID taking the action.

required
object (Access Request Recommendation Item)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

IAI Common Access

Get a paginated list of common access

This endpoint returns the current common access for a customer. The returned items can be filtered and sorted. Requires authorization scope of iai:access-modeling:read

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=access.type eq "ROLE"

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

Filtering is supported for the following fields and operators:

status: eq, sw

reviewedByUser eq

access.id: eq, sw

access.type: eq

access.name: sw, eq

access.description: sw, eq

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, status

By default the common access items are sorted by name, ascending.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create common access items

This API is used to add roles/access profiles to the list of common access for a customer. Requires authorization scope of iai:access-modeling:create

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
object (Common Access Item Access)
status
string (CommonAccessItemState)
Enum: "CONFIRMED" "DENIED"

State of common access item.

Responses

Request samples

Content type
application/json
{
  • "access": {
    },
  • "status": "CONFIRMED"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "access": {
    },
  • "status": "CONFIRMED",
  • "lastUpdated": "string",
  • "reviewedByUser": true,
  • "lastReviewed": "string",
  • "createdByUser": "string"
}

Bulk update common access status

This submits an update request to the common access application. At this time there are no parameters. Requires authorization scope of iai:access-modeling:update

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

Confirm or deny in bulk the common access ids that are (or aren't) common access

Array
confirmedIds
Array of strings <uuid>

List of confirmed common access ids.

deniedIds
Array of strings <uuid>

List of denied common access ids.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

IAI Message Catalogs

Get message catalogs

The getMessageCatalogs API returns message catalog based on the language headers in the requested object.

Authorizations:
Personal Access Token
path Parameters
catalog-id
required
string
Enum: "recommender" "access-request-recommender"
Example: recommender

The ID of the message catalog.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

IAI Outliers

Iai identity outliers summary

This API returns a summary containing the number of identities that customer has, the number of outliers, and the type of outlier.

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.

type
string
Enum: "LOW_SIMILARITY" "STRUCTURAL"
Example: type=LOW_SIMILARITY

Type of the identity outliers snapshot to filter on

filters
string
Example: filters=snapshotDate ge "2022-02-07T20:13:29.356648026Z"

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

Filtering is supported for the following fields and operators:

snapshotDate: ge, le

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

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

Sorting is supported for the following fields: snapshotDate

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Iai identity outliers latest summary

This API returns a most recent snapshot of each outlier type, each containing the number of identities that customer has, the number of outliers, and the type of outlier.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
type
string
Enum: "LOW_SIMILARITY" "STRUCTURAL"
Example: type=LOW_SIMILARITY

Type of the identity outliers snapshot to filter on

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Iai get identity outliers

This API returns a list of outliers, containing data such as identity ID, outlier type, detection dates, identity attributes, if identity is ignored, and certification information.

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.

type
string
Enum: "LOW_SIMILARITY" "STRUCTURAL"
Example: type=LOW_SIMILARITY

Type of the identity outliers snapshot to filter on

filters
string
Example: filters=attributes.displayName sw "John" and certStatus eq "false"

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

Filtering is supported for the following fields and operators:

attributes: eq, sw, co, in

firstDetectionDate: ge, le

certStatus: eq

ignored: eq

score: ge, le

sorters
string <comma-separated>
Example: sorters=attributes.displayName,firstDetectionDate,-score

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

Sorting is supported for the following fields: firstDetectionDate, attributes, score

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get identity outlier's contibuting features

This API returns a list of contributing feature objects for a single outlier.

The object contains: feature name, feature value type, value, importance, display name (translated text or message key), description (translated text or message key), translation messages object.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
outlierId
required
string
Example: 2c918085842e69ae018432d22ccb212f

The outlier 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.

include-translation-messages
string
Example: include-translation-messages=include-translation-messages=

Whether or not to include translation messages object in returned response

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

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

Sorting is supported for the following fields: importance

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Gets a list of access items associated with each identity outlier contributing feature

This API returns a list of the enriched access items associated with each feature filtered by the access item type.

The object contains: accessItemId, display name (translated text or message key), description (translated text or message key), accessType, sourceName, extremelyRare.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
outlierId
required
string
Example: 2c918085842e69ae018432d22ccb212f

The outlier id

contributingFeatureName
required
string
Enum: "radical_entitlement_count" "entitlement_count" "max_jaccard_similarity" "mean_max_bundle_concurrency" "single_entitlement_bundle_count" "peerless_score"
Example: entitlement_count

The name of contributing feature

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.

accessType
string
Example: accessType=ENTITLEMENT

The type of access item for the identity outlier contributing feature. If not provided, it returns all.

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

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

Sorting is supported for the following fields: displayName

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Iai identity outliers ignore

This API receives a list of identity IDs in the request, changes the outliers to be ignored.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "897ef96559df40e1baa6bae6b53e7340",
  • "2c918085837fbfb4018384420dac60c3"
]

Response samples

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

Iai identity outliers unignore

This API receives a list of identity IDs in the request, changes the outliers to be un-ignored.

Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "897ef96559df40e1baa6bae6b53e7340",
  • "2c918085837fbfb4018384420dac60c3"
]

Response samples

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

Iai identity outliers export

This API exports a list of ignored outliers to a CSV as well as list of non-ignored outliers to a CSV. These two CSVs will be zipped and exported.

Columns will include: identityId, type, firstDetectionDate, latestDetectionDate, ignored, & attributes (defined set of identity attributes).

Authorizations:
Personal Access TokenClient Credentials
query Parameters
type
string
Enum: "LOW_SIMILARITY" "STRUCTURAL"
Example: type=LOW_SIMILARITY

Type of the identity outliers snapshot to filter on

Responses

Response samples

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

Get identity outlier contibuting feature summary

This API returns a summary of a contributing feature for an identity outlier.

The object contains: contributing feature name (translated text or message key), identity outlier display name, feature values, feature definition and explanation (translated text or message key), peer display name and identityId, access item reference, translation messages object.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
outlierFeatureId
required
string
Example: 04654b66-7561-4090-94f9-abee0722a1af

Contributing feature id

Responses

Response samples

Content type
application/json
{
  • "contributingFeatureName": "Rare Access",
  • "identityOutlierDisplayName": "John Smith",
  • "outlierFeatureDisplayValues": [
    ],
  • "featureDefinition": "Identity total number of entitlements",
  • "featureExplanation": "An identity that has too much rare access has a higher change of becoming a security threat due to the unique access they possess",
  • "peerDisplayName": "Mary Jane",
  • "peerIdentityId": "9f9d5d53ad0e48fba7352f6da9f1b8gbg",
  • "accessItemReference": {
    }
}

IAI Peer Group Strategies

Identity outliers list Deprecated

-- Deprecated : See 'IAI Outliers' This API will be used by Identity Governance systems to identify identities that are not included in an organization's peer groups. By default, 250 identities are returned. You can specify between 1 and 1000 number of identities that can be returned.

Authorizations:
Personal Access Token
path Parameters
strategy
required
string
Value: "entitlement"
Example: entitlement

The strategy used to create peer groups. Currently, 'entitlement' is supported.

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
[
  • {
    }
]

IAI Recommendations

Returns recommendation based on object

The getRecommendations API returns recommendations based on the requested object. The recommendations are invoked by IdentityIQ and IdentityNow plug-ins that retrieve recommendations based on the performed calculations.

Authorizations:
Personal Access Token
Request Body schema: application/json
Array of objects (Recommendation Request)
excludeInterpretations
boolean
Default: "false"

Exclude interpretations in the response if "true". Return interpretations in the response if this attribute is not specified.

includeTranslationMessages
boolean
Default: "false"

When set to true, the calling system uses the translated messages for the specified language

includeDebugInformation
boolean
Default: "false"

Returns the recommender calculations if set to true

prescribeMode
boolean
Default: "false"

When set to true, uses prescribedRulesRecommenderConfig to get identity attributes and peer group threshold instead of standard config.

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ],
  • "excludeInterpretations": "false",
  • "includeTranslationMessages": "false",
  • "includeDebugInformation": "true",
  • "prescribeMode": "false"
}

Response samples

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

Get certification recommendation config values

Retrieves configuration attributes used by certification recommendations.

Authorizations:
Personal Access Token

Responses

Response samples

Content type
application/json
{
  • "recommenderFeatures": [
    ],
  • "peerGroupPercentageThreshold": 0.5,
  • "runAutoSelectOnce": false,
  • "onlyTuneThreshold": false
}

Update certification recommendation config values

Updates configuration attributes used by certification recommendations.

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

List of identity attributes to use for calculating certification recommendations

peerGroupPercentageThreshold
number <float> [ 0 .. 1 ]

The percent value that the recommendation calculation must surpass to produce a YES recommendation

runAutoSelectOnce
boolean
Default: false

If true, rulesRecommenderConfig will be refreshed with new programatically selected attribute and threshold values on the next pipeline run

onlyTuneThreshold
boolean
Default: false

If true, rulesRecommenderConfig will be refreshed with new programatically selected threshold values on the next pipeline run

Responses

Request samples

Content type
application/json
{
  • "recommenderFeatures": [
    ],
  • "peerGroupPercentageThreshold": 0.5,
  • "runAutoSelectOnce": false,
  • "onlyTuneThreshold": false
}

Response samples

Content type
application/json
{
  • "recommenderFeatures": [
    ],
  • "peerGroupPercentageThreshold": 0.5,
  • "runAutoSelectOnce": false,
  • "onlyTuneThreshold": false
}

IAI Role Mining

Create a role mining session

This submits a create role mining session request to the role mining application.

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

Role mining session parameters

object (Role Mining Session Scope)
pruneThreshold
integer or null <int32>

The prune threshold to be used or null to calculate prescribedPruneThreshold

prescribedPruneThreshold
integer or null <int32>

The calculated prescribedPruneThreshold

minNumIdentitiesInPotentialRole
integer or null <int32>

Minimum number of identities in a potential role

potentialRoleCount
integer <int32>

Number of potential roles

potentialRolesReadyCount
integer <int32>

Number of potential roles ready

type
string (RoleMiningRoleType)
Enum: "SPECIALIZED" "COMMON"

Role type

emailRecipientId
string or null

The id of the user who will receive an email about the role mining session

identityCount
integer <int32>

Number of identities in the population which meet the search criteria or identity list provided

saved
boolean
Default: false

The session's saved status

name
string or null

The session's saved name

Responses

Request samples

Content type
application/json
{
  • "scope": {
    },
  • "pruneThreshold": 50,
  • "prescribedPruneThreshold": 10,
  • "minNumIdentitiesInPotentialRole": 20,
  • "potentialRoleCount": 0,
  • "potentialRolesReadyCount": 0,
  • "type": "SPECIALIZED",
  • "emailRecipientId": "2c918090761a5aac0176215c46a62d58",
  • "identityCount": 0,
  • "saved": true,
  • "name": "Saved RM Session - 07/10"
}

Response samples

Content type
application/json
{
  • "scope": {
    },
  • "scopingMethod": "AUTO_RM",
  • "minNumIdentitiesInPotentialRole": 20,
  • "pruneThreshold": 70,
  • "prescribedPruneThreshold": 83,
  • "potentialRoleCount": 8,
  • "potentialRolesReadyCount": 4,
  • "status": {
    },
  • "type": "SPECIALIZED",
  • "emailRecipientId": null,
  • "createdBy": null,
  • "identityCount": 0,
  • "saved": false,
  • "name": null,
  • "dataFilePath": null,
  • "id": "602ba738-cf48-499b-a780-7b67b3fc1ecf",
  • "createdDate": "2021-09-08T16:11:05.348Z",
  • "modifiedDate": "2021-09-08T16:11:05.348Z"
}

Retrieves all role mining sessions

Returns all role mining sessions that match the query parameters

Authorizations:
Personal Access TokenClient Credentials
query Parameters
filters
string
Example: filters=saved eq "true" and name sw "RM Session"

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

Filtering is supported for the following fields and operators:

saved: eq

name: eq, sw

sorters
string <comma-separated>
Example: sorters=createdBy,createdDate

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

Sorting is supported for the following fields: createdBy, createdDate

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Patch a role mining session

The method updates an existing role mining session using PATCH. Supports op in {"replace"} and changes to pruneThreshold and/or minNumIdentitiesInPotentialRole. The potential roles in this role mining session is then re-calculated.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id to be patched

Request Body schema: application/json-patch+json

Replace pruneThreshold and/or minNumIdentitiesInPotentialRole in role mining session. Update saved status or saved name for a role mining session.

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
{ }

Get a role mining session

The method retrieves a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "scope": {
    },
  • "scopingMethod": "AUTO_RM",
  • "minNumIdentitiesInPotentialRole": 20,
  • "pruneThreshold": 70,
  • "prescribedPruneThreshold": 83,
  • "potentialRoleCount": 8,
  • "potentialRolesReadyCount": 4,
  • "status": {
    },
  • "type": "SPECIALIZED",
  • "emailRecipientId": null,
  • "createdBy": null,
  • "identityCount": 0,
  • "saved": false,
  • "name": null,
  • "dataFilePath": null,
  • "id": "602ba738-cf48-499b-a780-7b67b3fc1ecf",
  • "createdDate": "2021-09-08T16:11:05.348Z",
  • "modifiedDate": "2021-09-08T16:11:05.348Z"
}

Get role mining session status state

This method returns a role mining session status for a customer.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

Responses

Response samples

Content type
application/json
{
  • "state": "CREATED"
}

Retrieve session's potential role summaries

This method returns the potential role summaries for a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

query Parameters
sorters
string <comma-separated>
Example: sorters=createdDate

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

Sorting is supported for the following fields: createdDate

filters
string
Example: filters=(createdByName co "int")and (createdById sw "2c9180907")and (type eq "COMMON")and ((name co "entt")or (saved eq true))

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

Filtering is supported for the following fields and operators:

createdById: eq, sw, co

createdByName: eq, sw, co

description: sw, co

endDate: le, lt

freshness: eq, ge, gt, le, lt

name: eq, sw, co

quality: eq, ge, gt, le, lt

startDate: ge, gt

saved: eq

type: eq

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve potential role in session

This method returns a specific potential role for a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

Responses

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "density": 75,
  • "description": "Potential Role for Accounting dept",
  • "entitlementCount": 25,
  • "excludedEntitlements": [
    ],
  • "freshness": 75,
  • "identityCount": 25,
  • "identityDistribution": [
    ],
  • "identityIds": [
    ],
  • "identityGroupStatus": "OBTAINED",
  • "name": "Saved Potential Role - 07/10",
  • "potentialRoleRef": {
    },
  • "provisionState": "POTENTIAL",
  • "quality": 100,
  • "roleId": "07a0b4e2-7a76-44fa-bd0b-c64654b66519",
  • "saved": true,
  • "session": {
    },
  • "type": "SPECIALIZED",
  • "id": "e0cc5d7d-bf7f-4f81-b2af-8885b09d9923",
  • "createdDate": "2020-01-01T00:00:00.000Z",
  • "modifiedDate": "2020-01-01T00:00:00.000Z"
}

Update potential role in session

This method updates an existing potential role using the role mining session id and the potential role summary id.

The following fields can be modified:

  • description

  • name

  • saved

NOTE: All other fields cannot be modified.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The potential role summary id

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

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 "replace" operations

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Retrieves the applications of a potential role for a role mining session

This method returns the applications of a potential role for a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 62f28d91-7d9f-4d17-be15-666d5b41d77f

A potential role id in a role mining session

query Parameters
filters
string
Example: filters=applicationName sw "test"

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

Filtering is supported for the following fields and operators:

applicationName: sw

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves the entitlements of a potential role for a role mining session

This method returns the entitlements of a potential role for a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 62f28d91-7d9f-4d17-be15-666d5b41d77f

A potential role id in a role mining session

query Parameters
filters
string
Example: filters=entitlementRef.name sw "test"

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

Filtering is supported for the following fields and operators:

entitlementRef.name: sw

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves entitlements for a potential role in a role mining session

This method returns entitlements for a potential role in a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

query Parameters
includeCommonAccess
boolean
Default: true
Example: includeCommonAccess=true

Boolean determining whether common access entitlements will be included or not

sorters
string
Example: sorters=popularity

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

Sorting is supported for the following fields: popularity, entitlementName, applicationName

The default sort is popularity in descending order.

filters
string
Example: filters=applicationName sw "AD"

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

Filtering is supported for the following fields and operators:

applicationName: sw

entitlementRef.name: sw

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves entitlement popularity distribution for a potential role in a role mining session

This method returns entitlement popularity distribution for a potential role in a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

query Parameters
includeCommonAccess
boolean

Boolean determining whether common access entitlements will be included or not

Responses

Response samples

Content type
application/json
{
  • "property1": 0,
  • "property2": 0
}

Edit entitlements for a potential role to exclude some entitlements

This endpoint adds or removes entitlements from an exclusion list for a potential role.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

Request Body schema: application/json

Role mining session parameters

ids
Array of strings

The list of entitlement ids to be edited

exclude
boolean

If true, add ids to be exclusion list. If false, remove ids from the exclusion list.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "density": 75,
  • "description": "Potential Role for Accounting dept",
  • "entitlementCount": 25,
  • "excludedEntitlements": [
    ],
  • "freshness": 75,
  • "identityCount": 25,
  • "identityDistribution": [
    ],
  • "identityIds": [
    ],
  • "identityGroupStatus": "OBTAINED",
  • "name": "Saved Potential Role - 07/10",
  • "potentialRoleRef": {
    },
  • "provisionState": "POTENTIAL",
  • "quality": 100,
  • "roleId": "07a0b4e2-7a76-44fa-bd0b-c64654b66519",
  • "saved": true,
  • "session": {
    },
  • "type": "SPECIALIZED",
  • "id": "e0cc5d7d-bf7f-4f81-b2af-8885b09d9923",
  • "createdDate": "2020-01-01T00:00:00.000Z",
  • "modifiedDate": "2020-01-01T00:00:00.000Z"
}

Retrieves identities for a potential role in a role mining session

This method returns identities for a potential role in a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

query Parameters
sorters
string
Example: sorters=name

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

Sorting is supported for the following fields: name

filters
string

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

Filtering is supported for the following fields and operators:

name: sw

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export (download) details for a potential role in a role mining session

This endpoint downloads all the information for a potential role in a role mining session. Includes identities and entitlements in the potential role.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

Responses

Response samples

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

Asynchronously export details for a potential role in a role mining session and upload to s3

This endpoint uploads all the information for a potential role in a role mining session to S3 as a downloadable zip archive. Includes identities and entitlements in the potential role.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 278359a6-04b7-4669-9468-924cf580964a

A potential role id in a role mining session

Request Body schema: application/json
minEntitlementPopularity
integer

The minimum popularity among identities in the role which an entitlement must have to be included in the report

includeCommonAccess
boolean

If false, do not include entitlements that are highly popular among the entire orginization

Responses

Request samples

Content type
application/json
{
  • "minEntitlementPopularity": 0,
  • "includeCommonAccess": true
}

Response samples

Content type
application/json
{
  • "exportId": "0c6cdb76-1227-4aaf-af21-192dbdfbfa04",
  • "status": "QUEUED",
  • "minEntitlementPopularity": 0,
  • "includeCommonAccess": true
}

Retrieve status of a potential role export job

This endpoint retrieves information about the current status of a potential role export.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string <uuid>
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string <uuid>
Example: 278359a6-04b7-4669-9468-924cf580964a

A potential role id in a role mining session

exportId
required
string <uuid>
Example: 4940ffd4-836f-48a3-b2b0-6d498c3fdf40

The id of a previously run export job for this potential role

Responses

Response samples

Content type
application/json
{
  • "exportId": "0c6cdb76-1227-4aaf-af21-192dbdfbfa04",
  • "status": "QUEUED",
  • "minEntitlementPopularity": 0,
  • "includeCommonAccess": true
}

Export (download) details for a potential role in a role mining session

This endpoint downloads a completed export of information for a potential role in a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string <uuid>
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string <uuid>
Example: 278359a6-04b7-4669-9468-924cf580964a

A potential role id in a role mining session

exportId
required
string <uuid>
Example: 4940ffd4-836f-48a3-b2b0-6d498c3fdf40

The id of a previously run export job for this potential role

Responses

Response samples

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

Create request to provision a potential role into an actual role.

This method starts a job to provision a potential role

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

query Parameters
min-entitlement-popularity
integer [ 0 .. 100 ]
Default: 0

Minimum popularity required for an entitlement to be included in the provisioned role.

include-common-access
boolean
Default: true

Boolean determining whether common access entitlements will be included in the provisioned role.

Request Body schema: application/json

Required information to create a new role

roleName
string

Name of the new role being created

roleDescription
string

Short description of the new role being created

ownerId
string

ID of the identity that will own this role

includeIdentities
boolean
Default: false

When true, create access requests for the identities associated with the potential role

directlyAssignedEntitlements
boolean
Default: false

When true, assign entitlements directly to the role; otherwise, create access profiles containing the entitlements

Responses

Request samples

Content type
application/json
{
  • "roleName": "Finance - Accounting",
  • "roleDescription": "General access for accounting department",
  • "ownerId": "2b568c65bc3c4c57a43bd97e3a8e41",
  • "includeIdentities": true,
  • "directlyAssignedEntitlements": false
}

Response samples

Content type
application/json
{
  • "id": "e0cc5d7d-bf7f-4f81-b2af-8885b09d9923",
  • "name": "Potential Role - e0cc5d",
  • "potentialRoleRef": {
    },
  • "identityCount": 25,
  • "entitlementCount": 15,
  • "identityGroupStatus": "OBTAINED",
  • "provisionState": "POTENTIAL",
  • "roleId": "2a4be6fbcf3c4e66b95a0c15ffd591",
  • "density": 90,
  • "freshness": 70,
  • "quality": 80,
  • "type": "SPECIALIZED",
  • "createdBy": {
    },
  • "createdDate": "2019-08-24T14:15:22Z",
  • "saved": true,
  • "description": "string",
  • "session": {
    }
}

Retrieves excluded entitlements for a potential role in a role mining session

This method returns excluded entitlements for a potential role in a role mining session.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
sessionId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The role mining session id

potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id in a role mining session

query Parameters
sorters
string
Example: sorters=populariity

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

Sorting is supported for the following fields: popularity

filters
string
Example: filters=applicationName sw "AD"

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

Filtering is supported for the following fields and operators:

applicationName: sw

entitlementRef.name: sw

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves all potential role summaries

Returns all potential role summaries that match the query parameters

Authorizations:
Personal Access TokenClient Credentials
query Parameters
sorters
string <comma-separated>
Example: sorters=createdDate

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

Sorting is supported for the following fields: createdDate, identityCount, entitlementCount, freshness, quality

filters
string
Example: filters=(createdByName co "int") and (createdById sw "2c9180907") and (type eq "COMMON") and ((name co "entt") or (saved eq true))

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

Filtering is supported for the following fields and operators:

createdById: eq, sw, co

createdByName: eq, sw, co

description: sw, co

endDate: le, lt

freshness: eq, ge, gt, le, lt

name: eq, sw, co, ge, gt, le, lt

quality: eq, ge, gt, le, lt

startDate: ge, gt

saved: eq

type: eq, ge, gt, le, lt

scopingMethod: eq

sessionState: eq

identityAttribute: co

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves a specific potential role

This method returns a specific potential role.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

A potential role id

Responses

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "density": 75,
  • "description": "Potential Role for Accounting dept",
  • "entitlementCount": 25,
  • "excludedEntitlements": [
    ],
  • "freshness": 75,
  • "identityCount": 25,
  • "identityDistribution": [
    ],
  • "identityIds": [
    ],
  • "identityGroupStatus": "OBTAINED",
  • "name": "Saved Potential Role - 07/10",
  • "potentialRoleRef": {
    },
  • "provisionState": "POTENTIAL",
  • "quality": 100,
  • "roleId": "07a0b4e2-7a76-44fa-bd0b-c64654b66519",
  • "saved": true,
  • "session": {
    },
  • "type": "SPECIALIZED",
  • "id": "e0cc5d7d-bf7f-4f81-b2af-8885b09d9923",
  • "createdDate": "2020-01-01T00:00:00.000Z",
  • "modifiedDate": "2020-01-01T00:00:00.000Z"
}

Update a potential role

This method updates an existing potential role.

The following fields can be modified:

  • description

  • name

  • saved

NOTE: All other fields cannot be modified.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
potentialRoleId
required
string
Example: 8c190e67-87aa-4ed9-a90b-d9d5344523fb

The potential role summary id

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

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 "replace" operations

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Retrieves all saved potential roles

This method returns all saved potential roles (draft roles).

Authorizations:
Personal Access TokenClient Credentials
query Parameters
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: modified

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves potential role source usage

This method returns source usageCount (as number of days in the last 90 days) for each identity in a potential role.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
potentialRoleId
required
string
Example: e0cc5d7d-bf7f-4f81-b2af-8885b09d9923

A potential role id

sourceId
required
string
Example: 2c9180877620c1460176267f336a106f

A source id

query Parameters
sorters
string <comma-separated>
Example: sorters=-usageCount

Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: displayName, email, usageCount

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Icons

Use this API to implement functionality related to object icons (application icons for example). With this functionality in place, administrators can set or remove an icon for specific object type for use throughout Identity Security Cloud.

Update an icon

This API endpoint updates an icon by object type and object id. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
objectType
required
string
Value: "application"
Example: application

Object type

objectId
required
string
Example: a291e870-48c3-4953-b656-fb5ce2a93169

Object id.

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

file with icon. Allowed mime-types ['image/png', 'image/jpeg']

Responses

Response samples

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

Delete an icon

This API endpoint delete an icon by object type and object id. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access TokenClient Credentials
path Parameters
objectType
required
string
Value: "application"
Example: application

Object type

objectId
required
string
Example: a291e870-48c3-4953-b656-fb5ce2a93169

Object id.

Responses

Response samples

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

Identities

Use this API to implement identity functionality. With this functionality in place, administrators can synchronize an identity's attributes with its various source attributes.

Identity Security Cloud uses identities as users' authoritative accounts. Identities can own other accounts, entitlements, and attributes.

An identity has a variety of attributes, such as an account name, an email address, a job title, and more. These identity attributes can be correlated with different attributes on different sources. For example, the identity John.Smith can own an account in the GitHub source with the account name John-Smith-Org, and Identity Security Cloud knows they are the same person with the same access and attributes.

In Identity Security Cloud, administrators often set up these synchronizations to get triggered automatically with a change or to run on a schedule. To manually synchronize attributes for an identity, administrators can use the Identities drop-down menu and select Identity List to view the list of identities. They can then select the identity they want to manually synchronize and use the hamburger menu to select 'Synchronize Attributes.' Doing so immediately begins the attribute synchronization and analyzes all accounts for the selected identity.

Refer to Synchronizing Attributes for more information about synchronizing attributes.

Attribute synchronization for single identity.

This end-point performs attribute synchronization for a selected identity. The endpoint can be called once in 10 seconds per identity. A token with ORG_ADMIN or API authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
identityId
required
string

The Identity id

Responses

Response samples

Content type
application/json
{
  • "id": "0f11f2a4-7c94-4bf3-a2bd-742580fe3dfc",
  • "status": "IN_PROGRESS",
  • "payload": {
    }
}

Get ownership details

Use this API to return an identity's owned objects that will cause problems for deleting the identity. Use this API as a checklist of objects that you need to reassign to a different identity before you can delete the identity. For a full list of objects owned by an identity, use the Search API. When you search for identities, the returned identities have a property, owns, that contains a more comprehensive list of identity's owned objects.

Authorizations:
Personal Access Token
path Parameters
identityId
required
string
Example: ff8081814d2a8036014d701f3fbf53fa

Identity ID.

Responses

Response samples

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

List identities

This API returns a list of identities.

Authorizations:
Personal Access Token
query Parameters
filters
string
Example: filters=id eq "6c9079b270a266a60170a2779fcb0006" or correlated 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

alias: eq, sw

firstname: eq, sw

lastname: eq, sw

email: eq, sw

cloudStatus: eq

processingState: eq

correlated: eq

protected: eq

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

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

Sorting is supported for the following fields: name, alias, cloudStatus

defaultFilter
string
Default: "CORRELATED_ONLY"
Enum: "CORRELATED_ONLY" "NONE"
Example: defaultFilter=NONE

Adds additional filter to filters query parameter.

CORRELATED_ONLY adds correlated=true and returns only identities that are correlated.

NONE does not add any and returns all identities that satisfy filters query parameter.

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.

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Identity details

This API returns a single identity using the Identity ID.

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

Identity Id

Responses

Response samples

Content type
application/json
{
  • "id": "01f04e428c484542a241dc89c303b178",
  • "name": "Walter White",
  • "created": "2023-01-03T21:16:22.432Z",
  • "modified": "2023-01-03T21:16:22.432Z",
  • "alias": "walter.white",
  • "emailAddress": "walter.white@example.com",
  • "processingState": "ERROR",
  • "identityStatus": "LOCKED",
  • "managerRef": {
    },
  • "isManager": true,
  • "lastRefresh": "2020-11-22T15:42:31.123Z",
  • "attributes": {
    },
  • "lifecycleState": {
    }
}

Delete identity

The API returns successful response if the requested identity was deleted.

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

Identity Id

Responses

Response samples

Content type
application/json
{
  • "message": "Identity is the owner of following resources",
  • "associationDetails": {
    }
}

Invite identities to register

This API submits a task for inviting given identities via email to complete registration. The invitation email will include the link. After selecting the link an identity will be able to set up password and log in into the system. Invitations expire after 7 days. By default invitations send to the work identity email. It can be changed in Admin > Identities > Identity Profiles by selecting corresponding profile and editing Invitation Options.

This task will send an invitation email only for unregistered identities.

The executed task status can be checked by Task Management > Get task status by ID.

Learn more about inviting identities here
Authorizations:
Personal Access Token
Request Body schema: application/json
ids
Array of strings or null

The list of Identities IDs to invite - required when 'uninvited' is false

uninvited
boolean
Default: false

indicator (optional) to invite all unregistered identities in the system within a limit 1000. This parameter makes sense only when 'ids' is empty.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "id12345",
  • "type": "QUARTZ",
  • "uniqueName": "Big Task",
  • "description": "A Really Big Task",
  • "parentName": "Parent Task",
  • "launcher": "sweep",
  • "target": {
    },
  • "created": "2020-07-11T21:23:15.000Z",
  • "modified": "2020-07-11T21:23:15.000Z",
  • "launched": "2020-07-11T21:23:15.000Z",
  • "completed": "2020-07-11T21:23:15.000Z",
  • "completionStatus": "SUCCESS",
  • "messages": [
    ],
  • "returns": [
    ],
  • "attributes": {
    },
  • "progress": "Started",
  • "percentComplete": 100,
  • "taskDefinitionSummary": {
    }
}

Send password reset email

This API sends an email with the link to start Password Reset. After selecting the link an identity will be able to set up a new password. Emails expire after 2 hours.

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

Identity ID

Request Body schema: application/json
sourceName
string or null

The source name where identity account password should be reset

via
required
string
Enum: "EMAIL_WORK" "EMAIL_PERSONAL" "LINK_WORK" "LINK_PERSONAL"

The method to send notification

Responses

Request samples

Content type
application/json
{
  • "sourceName": "Active Directory Source",
  • "via": "EMAIL_WORK"
}

Response samples

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

Process a list of identityids

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 endpoint will perform the following tasks:

  1. Calculate identity attributes, including applying or running any rules or transforms (e.g. calculate Lifecycle State at a point-in-time it's expected to change).
  2. Evaluate role assignments, leading to assignment of new roles and removal of existing roles.
  3. Enforce provisioning for any assigned accesses that haven't been fulfilled (e.g. failure due to source health).
  4. Recalculate manager relationships.
  5. Potentially clean-up identity processing errors, assuming the error has been resolved.

A token with ORG_ADMIN or HELPDESK authority is required to call this API.

Learn more about manually processing identities here
Authorizations:
Personal Access TokenClient Credentials
Request Body schema: application/json
identityIds
Array of strings [ 1 .. 250 ] items

List of up to 250 identity IDs to process.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "type": "TASK_RESULT",
  • "id": "78733556-9ea3-4f59-bf69-e5cd92b011b4",
  • "name": "null"
}

Reset an identity

Use this endpoint to reset a user's identity if they have forgotten their authentication information like their answers to knowledge-based questions. Resetting an identity de-registers the user and removes any elevated user levels they have.

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

Identity Id

Responses

Response samples

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

List role assignments

This returns either a list of Role Assignments when querying with either a Role Id or Role Name, or a list of Role Assignment References if querying with only identity Id.

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

Identity Id to get the role assignments for

query Parameters
roleId
string
Example: roleId=e7697a1e96d04db1ac7b0f4544915d2c

Role Id to filter the role assignments with

roleName
string
Example: roleName=Engineer

Role name to filter the role assignments with

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Role assignment details

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

Identity Id

assignmentId
required
string
Example: 1cbb0705b38c4226b1334eadd8874086

Assignment Id

Responses

Response samples

Content type
application/json
{
  • "id": "1cbb0705b38c4226b1334eadd8874086",
  • "role": {
    },
  • "comments": "I'm a new Engineer and need this role to do my work",
  • "assignmentSource": "UI",
  • "assigner": {
    },
  • "assignedDimensions": [
    ],
  • "assignmentContext": {
    },
  • "accountTargets": [
    ],
  • "startDate": "2026-07-10T18:45:37.098Z",
  • "removeDate": "2026-07-11T18:45:37.098Z",
  • "addedDate": "2025-07-11T18:45:37.098Z"
}

Identity Attributes

List identity attributes

Use this API to get a collection of identity attributes.

Authorizations:
Personal Access TokenClient Credentials
query Parameters
includeSystem
boolean
Default: false

Include 'system' attributes in the response.

includeSilent
boolean
Default: false

Include 'silent' attributes in the response.

searchableOnly
boolean
Default: false

Include only 'searchable' attributes in the response.

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 identity attribute

Use this API to create a new identity attribute. A token with ORG_ADMIN authority is required to call this API.

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

Identity attribute's technical name.

displayName
string

Identity attribute's business-friendly name.

standard
boolean
Default: false

Indicates whether the attribute is 'standard' or 'default'.

type
string or null

Identity attribute's type.

multi
boolean
Default: false

Indicates whether the identity attribute is multi-valued.

searchable
boolean
Default: false

Indicates whether the identity attribute is searchable.

system
boolean
Default: false

Indicates whether the identity attribute is 'system', meaning that it doesn't have a source and isn't configurable.

Array of objects (Source)

Identity attribute's list of sources - this specifies how the rule's value is derived.

Responses

Request samples

Content type
application/json
{
  • "name": "costCenter",
  • "displayName": "Cost Center",
  • "standard": false,
  • "type": "string",
  • "multi": false,
  • "searchable": false,
  • "system": false,
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "costCenter",
  • "displayName": "Cost Center",
  • "standard": false,
  • "type": "string",
  • "multi": false,
  • "searchable": false,
  • "system": false,
  • "sources": [
    ]
}

Get identity attribute

This gets an identity attribute for a given technical name.

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

The attribute's technical name.

Responses

Response samples

Content type
application/json
{
  • "name": "costCenter",
  • "displayName": "Cost Center",
  • "standard": false,
  • "type": "string",
  • "multi": false,
  • "searchable": false,
  • "system": false,
  • "sources": [
    ]
}

Update identity attribute

This updates an existing identity attribute. Making an attribute searchable requires that the system, standard, and multi properties be set to false. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
name
required
string
Example: displayName

The attribute's technical name.

Request Body schema: application/json
name
required
string

Identity attribute's technical name.

displayName
string

Identity attribute's business-friendly name.

standard
boolean
Default: false

Indicates whether the attribute is 'standard' or 'default'.

type
string or null

Identity attribute's type.

multi
boolean
Default: false

Indicates whether the identity attribute is multi-valued.

searchable
boolean
Default: false

Indicates whether the identity attribute is searchable.

system
boolean
Default: false

Indicates whether the identity attribute is 'system', meaning that it doesn't have a source and isn't configurable.

Array of objects (Source)

Identity attribute's list of sources - this specifies how the rule's value is derived.

Responses

Request samples

Content type
application/json
{
  • "name": "costCenter",
  • "displayName": "Cost Center",
  • "standard": false,
  • "type": "string",
  • "multi": false,
  • "searchable": false,
  • "system": false,
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "costCenter",
  • "displayName": "Cost Center",
  • "standard": false,
  • "type": "string",
  • "multi": false,
  • "searchable": false,
  • "system": false,
  • "sources": [
    ]
}

Delete identity attribute

This deletes an identity attribute with the given name. The system and standard properties must be set to false before you can delete an identity attribute. A token with ORG_ADMIN authority is required to call this API.

Authorizations:
Personal Access Token
path Parameters
name
required
string
Example: displayName

The attribute's technical name.

Responses

Response samples

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

Bulk delete identity attributes

Use this API to bulk delete identity attributes for a given set of names. Attributes that are currently mapped in an identity profile cannot be deleted. The system and standard properties must be set to 'false' before you can delete an identity attribute. A token with ORG_ADMIN authority is required to call this API.

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

List of identity attributes' technical names.

Responses

Request samples

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

Response samples

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

Identity History

Lists all the identities

This gets the list of identities for the customer. This list end point does not support count=true request param. The total count of identities would never be returned even if the count param is specified in the request Requires authorization scope of 'idn:identity-history:read'

Authorizations:
Personal Access TokenClient Credentials
query Parameters
starts-with-query
string
Example: starts-with-query=Ada

This param is used for starts-with search for first, last and display name of the identity

is-deleted
boolean
Example: is-deleted=true

Indicates if we want to only list down deleted identities or not.

is-active
boolean
Example: is-active=true

Indicates if we want to only list active or inactive identities.

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get latest snapshot of identity

This method retrieves a specified identity Requires authorization scope of 'idn:identity-history:read'

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

The identity id

Responses

Response samples

Content type
application/json
{
  • "id": "bc693f07e7b645539626c25954c58554",
  • "displayName": "Adam Zampa",
  • "snapshot": "2007-03-01T13:00:00.000Z",
  • "deletedDate": "2007-03-01T13:00:00.000Z",
  • "accessItemCount": {
    },
  • "attributes": {
    }
}

List access items by identity

This method retrieves a list of access item for the identity filtered by the access item type

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

The identity id

query Parameters
type
string
Enum: "account" "entitlement" "app" "accessProfile" "role"
Example: type=account

The type of access item for the identity. If not provided, it defaults to account.

Types of access items: accessProfile, account, app, entitlement, role

filters
string
Example: filters=source eq "DataScienceDataset"

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

Filtering is supported for the following fields and operators:

source: eq

standalone: eq

privileged: eq

attribute: eq

cloudGoverned: eq

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, value, standalone, privileged, attribute, source, cloudGoverned, removeDate, nativeIdentity, entitlementCount

query
string
Example: query=Dr. Arden

This param is used to search if certain fields of the access item contain the string provided.

Searching is supported for the following fields depending on the type:

Access Profiles: name, description

Accounts: name, nativeIdentity

Apps: name

Entitlements: name, value, description

Roles: name, description

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.

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.

Responses

Response samples

Content type
application/json
Example

An access profile response

[
  • {
    }
]

Lists all the snapshots for the identity

This method retrieves all the snapshots for the identity Requires authorization scope of 'idn:identity-history:read'

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

The identity id

query Parameters
start
string
Example: start=2007-03-01T13:00:00Z

The specified start date

interval
string
Enum: "day" "month"

The interval indicating the range in day or month for the specified interval-name

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
[
  • {
    }
]

Gets the summary for the event count for a specific identity

This method gets the summary for the event count for a specific identity by month/day Requires authorization scope of 'idn:identity-history:read'

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

The identity id

query Parameters
before
string
Example: before=2007-03-01T13:00:00Z

The date before which snapshot summary is required

interval
string
Enum: "day" "month"

The interval indicating day or month. Defaults to month if not specified

time-zone
string
Example: time-zone=UTC

The time zone. Defaults to UTC if not provided

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
[
  • {
    }
]

Gets an identity snapshot at a given date

This method retrieves a specified identity snapshot at a given date Requires authorization scope of 'idn:identity-history:read'

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

The identity id

date
required
string
Example: 2007-03-01T13:00:00Z

The specified date

Responses

Response samples

Content type
application/json
{
  • "id": "bc693f07e7b645539626c25954c58554",
  • "displayName": "Adam Zampa",
  • "snapshot": "2007-03-01T13:00:00.000Z",
  • "deletedDate": "2007-03-01T13:00:00.000Z",
  • "accessItemCount": {
    },
  • "attributes": {
    }
}

Get identity access items snapshot

Use this API to get a list of identity access items at a specified date, filtered by item type.

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

Identity ID.

date
required
string
Example: 2007-03-01T13:00:00Z

Specified date.

query Parameters
type
string
Enum: "role" "access_profile" "entitlement" "app" "account"
Example: type=account

Access item type.

Responses

Response samples

Content type
application/json
Example

An access profile response

[
  • {
    }
]

List identity event history

This method retrieves all access events for the identity Requires authorization scope of 'idn:identity-history:read'

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

The identity id

query Parameters
from
string
Example: from=2024-03-01T13:00:00Z

The optional instant until which access events are returned

eventTypes
Array of strings
Example: eventTypes=AccessAddedEvent&eventTypes=AccessRemovedEvent

An optional list of event types to return. If null or empty, all events are returned

accessItemTypes
Array of strings
Example: accessItemTypes=entitlement&accessItemTypes=account

An optional list of access item types (app, account, entitlement, etc...) to return. If null or empty, all access items types are returned

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
Example

An Access item associated event

[
  • {
    }
]

Gets the start date of the identity

This method retrieves start date of the identity Requires authorization scope of 'idn:identity-history:read'

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

The identity id

Responses

Response samples

Content type
application/json
"2017-03-01T13:00:00.000Z"

Gets a difference of count for each access item types for the given identity between 2 snapshots

This method gets a difference of count for each access item types for the given identity between 2 snapshots Requires authorization scope of 'idn:identity-history:read'

Authorizations: