---
id: role-management-v2
title: Role Management APIs V2
sidebar_label: Roles V2
description: Role Management APIs V2 allow you to manage roles from HTTP endpoints.
slug: /help/docs/api/role-management-v2/
canonical: https://www.sumologic.com/help/docs/api/role-management-v2/
---

import useBaseUrl from '@docusaurus/useBaseUrl';
import ApiIntro from '../reuse/api-intro.md';
import ApiRoles from '../reuse/api-roles.md';

<img src={useBaseUrl('img/icons/operations/role-based-access.png')} alt="Role Based Access icon" width="50"/>

Roles determine the functions that users are able to perform in Sumo Logic. The Role Management API (V2) allows you to configure access on partitions and manage roles from HTTP endpoints.

To manage roles, you must have an administrator role or your role must have been assigned the [Manage Users and Roles](/docs/manage/users-roles/) capability.

## Documentation

<ApiIntro/>

| Region code | Region name | AWS region | API endpoint |
|:----|:----|:---|:-----|
| AU  | Asia Pacific (Sydney)  | ap-southeast-2 | https://api.au.sumologic.com/docs/#tag/roleManagementV2   |
| CA  | Canada (Central)       | ca-central-1   | https://api.ca.sumologic.com/docs/#tag/roleManagementV2   |
| CH  | Switzerland (Zurich)   | eu-central-2   | https://api.ch.sumologic.com/docs/#tag/roleManagementV2  |
| DE  | EU (Frankfurt)         | eu-central-1   | https://api.de.sumologic.com/docs/#tag/roleManagementV2   |
| ESC | AWS European Sovereign Cloud | eusc-de-east-1 | https://api.esc.sumologic.com/docs/#tag/roleManagementV2  |
| EU  | EU (Ireland)           | eu-west-1      | https://api.eu.sumologic.com/docs/#tag/roleManagementV2   |
| FED | US East (N. Virginia)  | us-east-1      | https://api.fed.sumologic.com/docs/#tag/roleManagementV2  |
| JP  | Asia Pacific (Tokyo)   | ap-northeast-1 | https://api.jp.sumologic.com/docs/#tag/roleManagementV2   |
| KR  | Asia Pacific (Seoul)   | ap-northeast-2 | https://api.kr.sumologic.com/docs/#tag/roleManagementV2   |
| US1 | US East (N. Virginia)  | us-east-1      | https://api.sumologic.com/docs/#tag/roleManagementV2      |
| US2 | US West (Oregon)       | us-west-2      | https://api.us2.sumologic.com/docs/#tag/roleManagementV2  |

## Migrate audit logs queries from Role Management API V1 to V2

If you use role-based [audit data filtering](/docs/manage/users-roles/roles/create-manage-roles/#create-a-role), we recommend you migrate the search from V1 to V2 audit logging.

With advanced search filters added, you can obtain more granular information about the selected role. The `filterPredicate` field in V1 audit logging is replaced with `logAnalyticsFilter`, `auditDataFilter`, and `securityDataFilter` fields in V2. In addition, we have also added `selectionType` and `selectedViews` fields to apply for audit data filtering.

Currently, Role Management APIs V2 records both the V1 and V2 log line changes.

:::note
V2 changes are **only** applicable for `RoleUpdate` and `RoleCreated` events.
:::

<br/><img src={useBaseUrl('img/users-roles/JSON-diff-V1-V2.png')} alt="JSON diff V1 V2" style={{border: '1px solid gray'}} width="800"/>

For example, consider you are interested in querying upon audit logs with change in `RoleUpdated` or `RoleCreated` events. Now, if you perform this search you will initially see the V1 type of event in the search results. However, to view the results with the V2 event type, you are required to adjust the parameters in the query.

```sumo title="V1 Audit Logging"
(_index=sumologic_audit_events)
| json fields=_raw "roleIdentity.roleName" as role_name
| json fields=_raw "eventTime" as eventTime
| json fields=_raw "role.filterPredicate" as create_role
| json fields=_raw "to.filterPredicate" as update_role
| json fields=_raw "operator.email" as actor
| json fields=_raw "eventName" | where eventName matches "RoleCreated" OR eventName="RoleUpdate"
| count by eventTime, eventName, actor, role_name, create_role, update_role
```

```sumo title="V2 Audit Logging"
(_index=sumologic_audit_events)
| json fields=_raw "roleIdentity.roleName" as role_name
| json fields=_raw "eventTime" as eventTime
| json fields=_raw "role.logAnalyticsFilter" as created_log_analytics_filter
| json fields=_raw "role.auditDataFilter" as created_audit_data_filter
| json fields=_raw "to.logAnalyticsFilter" as updated_log_analytics_filter
| json fields=_raw "to.auditDataFilter" as updated_audit_data_filter
| json fields=_raw "operator.email" as actor
| json fields=_raw "eventName" | where eventName matches "RoleCreatedV2" OR eventName="RoleUpdateV2"
| count by eventTime, eventName, actor, role_name, created_log_analytics_filter, created_audit_data_filter, updated_log_analytics_filter, updated_log_analytics_filter
```

## Required role capabilities

<ApiRoles/>

* [User Management](/docs/manage/users-roles/roles/role-capabilities/#user-management) (all role capabilities)