sailpoint.v2024.RolesApi

Use this API to implement and customize role functionality. With this functionality in place, administrators can create roles and configure them for use throughout Identity Security Cloud. Identity Security Cloud can use established criteria to automatically assign the roles to qualified users. This enables users to get all the access they need quickly and securely and administrators to spend their time on other tasks.

Entitlements represent the most granular level of access in Identity Security Cloud. Access profiles represent the next level and often group entitlements. Roles represent the broadest level of access and often group access profiles.

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

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

An administrator can then create an even broader set of access in the form of a role grouping the 'AD Developers' access profile with another profile, 'GitHub Developers,' grouping entitlements for the GitHub source.

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

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

When users need both the 'AD Developers' access profile and the 'GitHub Developers' access profile, they can request access to the role grouping both.

Roles often represent positions within organizations. For example, an organization's accountant can access all the tools the organization's accountants need with the 'Accountant' role. If the accountant switches to engineering, a qualified member of the organization can quickly revoke the accountant's 'Accountant' access and grant access to the 'Engineer' role instead, granting access to all the tools the organization's engineers need.

In Identity Security Cloud, adminstrators can use the Access drop-down menu and select Roles to view, configure, and delete existing roles, as well as create new ones. Administrators can enable and disable the role, and they can also make the following configurations:

Manage Access: Manage the role's access by adding or removing access profiles.
Define Assignment: Define the criteria Identity Security Cloud uses to assign the role to identities. Use the first option, 'Standard Criteria,' to provide specific criteria for assignment like specific account attributes, entitlements, or identity attributes. Use the second, 'Identity List,' to specify the identities for assignment.
Access Requests: Configure roles to be requestable and establish an approval process for any requests that the role be granted or revoked. Do not configure a role to be requestable without establishing a secure access request approval process for that role first.

Refer to Working with Roles for more information about roles.

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

Method	HTTP request	Description
create-role	POST `/roles`	Create a Role
delete-bulk-roles	POST `/roles/bulk-delete`	Delete Role(s)
delete-metadata-from-role-by-key-and-value	DELETE `/roles/{id}/access-model-metadata/{attributeKey}/values/{attributeValue}`	Remove a Metadata From Role.
delete-role	DELETE `/roles/{id}`	Delete a Role
get-bulk-update-status	GET `/roles/access-model-metadata/bulk-update`	Get Bulk-Update Statuses
get-bulk-update-status-by-id	GET `/roles/access-model-metadata/bulk-update/id`	Get Bulk-Update Status by ID
get-role	GET `/roles/{id}`	Get a Role
get-role-assigned-identities	GET `/roles/{id}/assigned-identities`	List Identities assigned a Role
get-role-entitlements	GET `/roles/{id}/entitlements`	List Role's Entitlements
list-roles	GET `/roles`	List Roles
patch-role	PATCH `/roles/{id}`	Patch a specified Role
search-roles-by-filter	POST `/roles/filter`	Filter Roles by Metadata
update-attribute-key-and-value-to-role	POST `/roles/{id}/access-model-metadata/{attributeKey}/values/{attributeValue}`	Add a Metadata to Role.
update-roles-metadata-by-filter	POST `/roles/access-model-metadata/bulk-update/filter`	Bulk-Update Roles' Metadata by Filters
update-roles-metadata-by-ids	POST `/roles/access-model-metadata/bulk-update/ids`	Bulk-Update Roles' Metadata by ID
update-roles-metadata-by-query	POST `/roles/access-model-metadata/bulk-update/query`	Bulk-Update Roles' Metadata by Query

create-role

Create a Role This API creates a role.

You must have a token with API, ORG_ADMIN, ROLE_ADMIN, or ROLE_SUBADMIN authority to call this API.

In addition, a ROLE_SUBADMIN may not create a role including an access profile if that access profile is associated with a source the ROLE_SUBADMIN is not associated with themselves.

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

API Spec

Parameters

Param Type	Name	Data Type	Required	Description
Body	role	Role	True

Return type

Role

Responses

Code	Description	Data Type	Response headers
201	Role created	Role	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

HTTP request headers

Content-Type: application/json
Accept: application/json

Example

from sailpoint.v2024.api.roles_api import RolesApi
from sailpoint.v2024.api_client import ApiClient
from sailpoint.v2024.models.role import Role
from sailpoint.configuration import Configuration
configuration = Configuration()


with ApiClient(configuration) as api_client:
    role = '''{
          "owner" : {
            "name" : "support",
            "id" : "2c9180a46faadee4016fb4e018c20639",
            "type" : "IDENTITY"
          },
          "entitlements" : [ {
            "name" : "CN=entitlement.490efde5,OU=OrgCo,OU=ServiceDept,DC=HQAD,DC=local",
            "id" : "2c91809773dee32014e13e122092014e",
            "type" : "ENTITLEMENT"
          }, {
            "name" : "CN=entitlement.490efde5,OU=OrgCo,OU=ServiceDept,DC=HQAD,DC=local",
            "id" : "2c91809773dee32014e13e122092014e",
            "type" : "ENTITLEMENT"
          } ],
          "dimensional" : false,
          "created" : "2021-03-01T22:32:58.104Z",
          "dimensionRefs" : [ {
            "name" : "Role 2",
            "id" : "2c91808568c529c60168cca6f90c1313",
            "type" : "DIMENSION"
          }, {
            "name" : "Role 2",
            "id" : "2c91808568c529c60168cca6f90c1313",
            "type" : "DIMENSION"
          } ],
          "description" : "Urna amet cursus pellentesque nisl orci maximus lorem nisl euismod fusce morbi placerat adipiscing maecenas nisi tristique et metus et lacus sed morbi nunc nisl maximus magna arcu varius sollicitudin elementum enim maecenas nisi id ipsum tempus fusce diam ipsum tortor.",
          "membership" : {
            "identities" : [ {
              "aliasName" : "t.edison",
              "name" : "Thomas Edison",
              "id" : "2c9180a46faadee4016fb4e018c20639",
              "type" : "IDENTITY"
            }, {
              "aliasName" : "t.edison",
              "name" : "Thomas Edison",
              "id" : "2c9180a46faadee4016fb4e018c20639",
              "type" : "IDENTITY"
            } ],
            "criteria" : {
              "stringValue" : "[email protected]",
              "children" : [ {
                "stringValue" : "[email protected]",
                "children" : [ {
                  "stringValue" : "[email protected]",
                  "operation" : "EQUALS",
                  "key" : {
                    "sourceId" : "2c9180867427f3a301745aec18211519",
                    "property" : "attribute.email",
                    "type" : "ACCOUNT"
                  }
                }, {
                  "stringValue" : "[email protected]",
                  "operation" : "EQUALS",
                  "key" : {
                    "sourceId" : "2c9180867427f3a301745aec18211519",
                    "property" : "attribute.email",
                    "type" : "ACCOUNT"
                  }
                } ],
                "operation" : "EQUALS",
                "key" : {
                  "sourceId" : "2c9180867427f3a301745aec18211519",
                  "property" : "attribute.email",
                  "type" : "ACCOUNT"
                }
              }, {
                "stringValue" : "[email protected]",
                "children" : [ {
                  "stringValue" : "[email protected]",
                  "operation" : "EQUALS",
                  "key" : {
                    "sourceId" : "2c9180867427f3a301745aec18211519",
                    "property" : "attribute.email",
                    "type" : "ACCOUNT"
                  }
                }, {
                  "stringValue" : "[email protected]",
                  "operation" : "EQUALS",
                  "key" : {
                    "sourceId" : "2c9180867427f3a301745aec18211519",
                    "property" : "attribute.email",
                    "type" : "ACCOUNT"
                  }
                } ],
                "operation" : "EQUALS",
                "key" : {
                  "sourceId" : "2c9180867427f3a301745aec18211519",
                  "property" : "attribute.email",
                  "type" : "ACCOUNT"
                }
              } ],
              "operation" : "EQUALS",
              "key" : {
                "sourceId" : "2c9180867427f3a301745aec18211519",
                "property" : "attribute.email",
                "type" : "ACCOUNT"
              }
            },
            "type" : "IDENTITY_LIST"
          },
          "enabled" : true,
          "revocationRequestConfig" : {
            "commentsRequired" : false,
            "approvalSchemes" : [ {
              "approverId" : "46c79819-a69f-49a2-becb-12c971ae66c6",
              "approverType" : "GOVERNANCE_GROUP"
            }, {
              "approverId" : "46c79819-a69f-49a2-becb-12c971ae66c6",
              "approverType" : "GOVERNANCE_GROUP"
            } ],
            "denialCommentsRequired" : false
          },
          "segments" : [ "f7b1b8a3-5fed-4fd4-ad29-82014e137e19", "29cb6c06-1da8-43ea-8be4-b3125f248f2a" ],
          "legacyMembershipInfo" : {
            "type" : "IDENTITY_LIST"
          },
          "accessRequestConfig" : {
            "commentsRequired" : true,
            "reauthorizationRequired" : true,
            "approvalSchemes" : [ {
              "approverId" : "46c79819-a69f-49a2-becb-12c971ae66c6",
              "approverType" : "GOVERNANCE_GROUP"
            }, {
              "approverId" : "46c79819-a69f-49a2-becb-12c971ae66c6",
              "approverType" : "GOVERNANCE_GROUP"
            } ],
            "denialCommentsRequired" : true
          },
          "accessProfiles" : [ {
            "name" : "Access Profile 2567",
            "id" : "ff808081751e6e129f1518161919ecca",
            "type" : "ACCESS_PROFILE"
          }, {
            "name" : "Access Profile 2567",
            "id" : "ff808081751e6e129f1518161919ecca",
            "type" : "ACCESS_PROFILE"
          } ],
          "name" : "Role 2567",
          "modified" : "2021-03-02T20:22:28.104Z",
          "accessModelMetadata" : {
            "attributes" : [ {
              "key" : "iscPrivacy",
              "name" : "Privacy",
              "multiselect" : false,
              "status" : "active",
              "type" : "governance",
              "objectTypes" : [ "all" ],
              "description" : "Specifies the level of privacy associated with an access item.",
              "values" : [ {
                "value" : "public",
                "name" : "Public",
                "status" : "active"
              } ]
            } ]
          },
          "id" : "2c918086749d78830174a1a40e121518",
          "requestable" : true
        }''' # Role | 

    try:
        # Create a Role
        new_role = Role.from_json(role)
        results = RolesApi(api_client).create_role(role=new_role)
        # Below is a request that includes all optional parameters
        # results = RolesApi(api_client).create_role(new_role)
        print("The response of RolesApi->create_role:\n")
        print(results.model_dump_json(by_alias=True, indent=4))
    except Exception as e:
        print("Exception when calling RolesApi->create_role: %s\n" % e)

Code	Description	Data Type	Response headers
202	Returns an object with the id of the task performing the delete operation.	TaskResultDto	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Param Type	Name	Data Type	Required	Description
Path	id	str	True	The role's id.
Path	attribute_key	str	True	Technical name of the Attribute.
Path	attribute_value	str	True	Technical name of the Attribute Value.

Code	Description	Data Type	Response headers
202	Request accepted		-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
204	No content - indicates the request was successful but there is no content to be returned in the response.		-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	successfully get the status of all unfinished bulk updates request.	List[RoleGetAllBulkUpdateResponse]	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
202	return if bulk update status could be found.	RoleBulkUpdateResponse	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	List of all Roles	Role	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	List of Identities assigned the Role	List[RoleIdentity]	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	List of Entitlements	List[Entitlement]	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Param Type	Name	Data Type	Required	Description
Query	for_subadmin	str	(optional)	If provided, filters the returned list according to what is visible to the indicated ROLE_SUBADMIN Identity. The value of the parameter is either an Identity ID, or the special value me, which is shorthand for the calling Identity's ID. A 400 Bad Request error is returned if the for-subadmin parameter is specified for an Identity that is not a subadmin.
Query	limit	int	(optional) (default to 50)	Note that for this API the maximum value for limit is 50. See V3 API Standard Collection Parameters for more information.
Query	offset	int	(optional) (default to 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.
Query	count	bool	(optional) (default to False)	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.
Query	filters	str	(optional)	Filter results using the standard syntax described in V3 API Standard Collection Parameters Filtering is supported for the following fields and operators: id: eq, in name: eq, sw created: gt, ge, le modified: lt, ge, le owner.id: eq, in requestable: eq dimensional: eq
Query	sorters	str	(optional)	Sort results using the standard syntax described in V3 API Standard Collection Parameters Sorting is supported for the following fields: name, created, modified
Query	for_segment_ids	str	(optional)	If present and not empty, additionally filters Roles to those which are assigned to the Segment(s) with the specified IDs. If segmentation is currently unavailable, specifying this parameter results in an error.
Query	include_unsegmented	bool	(optional) (default to True)	Whether or not the response list should contain unsegmented Roles. If for-segment-ids is absent or empty, specifying include-unsegmented as false results in an error.

Code	Description	Data Type	Response headers
200	List of Roles	List[Role]	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	Responds with the Role as updated.	Role	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
200	Responds with A list of Roles	Role[str]	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

Code	Description	Data Type	Response headers
202	Returned if bulk update request created	RoleBulkUpdateResponse	-
400	Client Error - Returned if the request body is invalid.	ErrorResponseDto	-
401	Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.	ListAccessProfiles401Response	-
403	Forbidden - Returned if the user you are running as, doesn't have access to this end-point.	ErrorResponseDto	-
429	Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.	ListAccessProfiles429Response	-
500	Internal Server Error - Returned if there is an unexpected error.	ErrorResponseDto	-

create-role​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

delete-bulk-roles​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

delete-metadata-from-role-by-key-and-value​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

delete-role​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-bulk-update-status​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-bulk-update-status-by-id​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-assigned-identities​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

get-role-entitlements​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

list-roles​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

patch-role​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

search-roles-by-filter​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

update-attribute-key-and-value-to-role​

Parameters​

Return type​

Responses​

HTTP request headers​

Example​

update-roles-metadata-by-filter​

Parameters​

create-role

Parameters

Return type

Responses

HTTP request headers

Example

delete-bulk-roles

Parameters

Return type

Responses

HTTP request headers

Example

delete-metadata-from-role-by-key-and-value

Parameters

Return type

Responses

HTTP request headers

Example

delete-role

Parameters

Return type

Responses

HTTP request headers

Example

get-bulk-update-status

Parameters

Return type

Responses

HTTP request headers

Example

get-bulk-update-status-by-id

Parameters

Return type

Responses

HTTP request headers

Example

get-role

Parameters

Return type

Responses

HTTP request headers

Example

get-role-assigned-identities

Parameters

Return type

Responses

HTTP request headers

Example

get-role-entitlements

Parameters

Return type

Responses

HTTP request headers

Example

list-roles

Parameters

Return type

Responses

HTTP request headers

Example

patch-role

Parameters

Return type

Responses

HTTP request headers

Example

search-roles-by-filter

Parameters

Return type

Responses

HTTP request headers

Example

update-attribute-key-and-value-to-role

Parameters

Return type

Responses

HTTP request headers

Example

update-roles-metadata-by-filter

Parameters