--- title: Roles description: The following are Ping Autonomous Identity filtering by roles endpoints: component: autonomous-identity version: 2022.11.12 page_id: autonomous-identity:api-guide:chap-roles-api canonical_url: https://docs.pingidentity.com/autonomous-identity/2022.11.12/api-guide/chap-roles-api.html section_ids: api-roles: POST /api/roles api-roles-delete: POST /api/roles/delete api-roles-export: POST /api/roles/export --- # Roles The following are Ping Autonomous Identity filtering by roles endpoints: ## POST /api/roles * POST /api/roles Create draft roles and make updates to roles. Endpoint ``` /api/roles ``` Authorization ``` OR ``` **Request Body Parameters** | Parameter | Type | Description | | ----------------- | ----------- | ----------------------------------------------------------------------- | | action | string | Action to perform ('create', 'save', 'publish', 'unpublish') (required) | | updateAllMetadata | boolean | Update metadata for all related roles regardless of statuus | | role | role object | Role object (properties below) (required) | **Role Object Properties** | Parameter | Type | Description | | ---------------------- | ------------------------------------- | --------------------------------------------------------------------------- | | role\_id | string | Role ID in uuid format (required) | | status | string | Status of role ('draft', 'candidate', or 'active') (required) | | custom\_role | boolean | Role is a custom role | | member\_count | number | Number of users the roles applies to | | assignment\_count | number | Number of assignments the role applies to | | entitlements | string array | List of entitlement IDs that are part of the role | | justifications | string array | List of raw justifications | | datasink\_status | string | Datasink status ('ack' or 'nack') | | role\_metadata | role metadata object | Role metadata (properties below) | | entitlements\_metadata | array of entitlement metadata objects | List of entitlement metadata for each entitlement (object properties below) | **Role Metadata Object Properties** | Parameter | Type | Description | | -------------------------- | ------ | ----------------------- | | role\_name | string | Display name of role | | description | string | Role description | | role\_owner\_id | string | Role owner ID | | role\_owner\_display\_name | string | Role owner display name | **Entitlement Metadata Object Properties** | Parameter | Type | Description | | ------------------ | ------------------ | ------------------------------------------------ | | ent\_id | string | Entitlement ID (required) | | ent\_name | string | Entitlement name (required) | | application | application object | Application metadata (object properties below) | | entitlement\_owner | owner object | Entitlement owner data (object properties below) | **Application Object Properties** | Parameter | Type | Description | | ------------------ | ------------ | ------------------------------------------------ | | app\_id | string | Application ID | | app\_name | string | Application name | | application\_owner | owner object | Application owner data (object properties below) | **Owner Object Properties** | Parameter | Type | Description | | ---------------- | ------ | -------------------------- | | usr\_id | string | User ID (required) | | usr\_name | string | User name (required) | | usr\_manager\_id | string | User manager ID (required) | Example Request ``` curl --location --request POST 'https://autoid-api.forgerock.com/api/roles' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data-raw '{ "action": "save", "updateAllMetadata": false, "role": { "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft", "custom_role": false, "member_count": 0, "assignment_count": 0, "entitlements": [ "string" ], "entitlements_metadata": [ { "ent_id": "string", "ent_name": "string", "application": { "app_id": "string", "app_name": "string", "application_owner": { "usr_id": "string", "usr_name": "string", "usr_manager_id": "string" } }, "entitlement_owner": { "usr_id": "string", "usr_name": "string", "usr_manager_id": "string" } } ], "justifications": [ "string" ], "role_metadata": { "role_name": "string", "description": "string", "role_owner_display_name": "string", "role_owner_id": "string" } } }' ``` Example Response ``` 204 (No Content) ``` ## POST /api/roles/delete * POST /api/roles/delete Delete roles. Endpoint ``` /api/roles/delete ``` Authorization ``` ``` Body ``` { "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft" | "active" } ``` Example Request ``` curl --location --request POST 'https://autoid-api.forgerock.com/api/admin/updateSelf' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data-raw '{ "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft" | "active" }' ``` Example Response ``` 204 (No content) ``` ## POST /api/roles/export * POST /api/roles/export Export role data to json. Endpoint ``` /api/roles/export ``` Authorization ``` OR ``` **Query Parameters** | Parameter | Type | Description | | -------------------------- | ------ | ------------------------------------------------------- | | usrId | string | Roles that apply for a particular user ID | | entId | string | Roles that apply for a particular entitlement ID | | status | string | Status of role ('draft', 'candidate', or 'active') | | role\_name | string | Role name | | description | string | Role description | | role\_owner\_id | string | Role owner ID | | role\_owner\_display\_name | string | Role owner name | | datasinkStatus | string | Datasink status filter ('ack', 'nack') | | timestampThresholds | object | Timestamp threshold object (available properties below) | **timestampThresholds Object Properties** | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------- | | gt | string | Greater than timestamp (format: yyyy-mm-ddThh:mm:ss.SSSZ). Cannot be present with **gte**. | | gte | string | Greater than or equal timestamp (format: yyyy-mm-ddThh:mm:ss.SSSZ). Cannot be present with **gt**. | | lt | string | Less than timestamp (format: yyyy-mm-ddThh:mm:ss.SSSZ). Cannot be present with **lte**. | | lte | string | Less than or equal timestamp (format: yyyy-mm-ddThh:mm:ss.SSSZ). Cannot be present with **le**. | Body ``` { "usrId": "john.doe", "datasinkStatus": "nack" } ``` Example Request (Datasink Filter) ``` curl -k -X POST \ 'https://autoid-ui.forgerock.com/api/roles/export' \ --header 'Content-type: application/json' \ --header 'Authorization: Bearer ' -H 'X-API-KEY: ' \ --data-raw '{ "usrId": "john.doe", "datasinkStatus": "nack" }' ``` Example Response (Datasink Filter) ``` { "roles": [ { "temp_role_name": "Role J0-R21", "normalized_role_name": "role j0-r21", "member_count": 1, "assignment_count": 1, "entitlement_count": 1, "role_id": "4aaf81db-2f8c-42b4-b954-1018a71743de", "status": "candidate", "entitlements": [ "Ent_1" ], "entitlements_metadata": [ { "ent_criticality": "Essential", "ent_id": " Ent_1", "ent_name": " Ent_1", "ent_risk_level": "Low", "application": { "app_criticality": "Essential", "app_id": "Active Directory", "app_name": "Active Directory", "app_risk_level": "High", "application_owner": { "chief_yes_no": "Yes", "city": "Kansas City", "cost_center": "CON_SD9", "department": "Facilities Area A", "is_active": "Y", "job_description": "Facilities Area A", "jobcode_name": "Operating Clerk", "line_of_business": "Transmission Operations", "line_of_business_subgroup": "Real Estate", "manager_name": "Thomas Shawyer", "usr_department_name": "Facilities Area A", "usr_display_name": "Derick Hui", "usr_emp_type": "Non-Employee", "usr_id": "derick.hui", "usr_manager_id": "thomas.shawyer", "usr_name": "Derick Hui" } }, "entitlement_owner": { "chief_yes_no": "No", "city": "Saint Paul", "cost_center": "OP_TT4", "department": "InfoSYS Power Gen", "is_active": "Y", "job_description": "InfoSYS Power Gen", "jobcode_name": "Lineman", "line_of_business": "Ethics and Compliance", "line_of_business_subgroup": "System Operations", "manager_name": "James Bosch", "usr_department_name": "InfoSYS Power Gen", "usr_display_name": "Carolyn Latanafrancia", "usr_emp_type": "Non-Employee", "usr_id": "carolyn.latanafrancia", "usr_manager_id": "james.bosch", "usr_name": "Carolyn Latanafrancia" } } ], "justifications": [ "0B_COST_CENTER_SOL_ER2 19_LINE_OF_BUSINESS_SUBGROUP_Energy%20Solutions" ], "users": [ { "usr_id": "aaron.lozada", "usr_display_name": "Aaron Lozada", "attributes": [ "13_USR_DEPARTMENT_NAME_Operations%20SUP", "0F_JOB_DESCRIPTION_Operations_%20SUP", "0C_JOBCODE_NAME_Apprentice", "0C_MANAGER_NAME_Gary%20Amelio", "09_IS_ACTIVE_Y", "10_LINE_OF_BUSINESS_Distribution%20Operations", "10_USR_DISPLAY_NAME_Aaron%20Lozada", "0B_COST_CENTER_SOL_ER2", "08_USR_NAME_Aaron%20Lozada", "0C_CHIEF_YES_NO_No", "0C_USR_EMP_TYPE_Employee", "19_LINE_OF_BUSINESS_SUBGROUP_Energy%20Solutions", "04_CITY_Kansas%20City" ] } ] } ] } ```