> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating a User's Role & Organization

The Groups APIs can be used to update a user's role and organization. In the OneTrust application, a SCIM group is a combination of a role and organization. If your account has 20 roles and 2 organizations, that effectively means that you have 20 x 2 = 40 unique groups.

## Steps

1. Obtain the user's unique id
2. Identify the SCIM group that corresponds to the required role and organization
3. Obtain the group's id
4. Use the Groups API to add the user to the group or to remove the user from the group

## What parameters are required to update a user's role or organization?

1. The user's unique id represented by `id`
2. The group's unique id represented by `groupId`

## Step 1: Obtaining the user's unique id `id`

The [GET /Users](/onetrust/reference/getallusersusingget) endpoint can be used to retrieve the list of all Active and Inactive users in the account. If any of the user's basic attributes such as 'First Name', Last Name' or 'Email Address' are known, they can be used to obtain the user's `id`.

*Example Request:*

```
GET /api/scim/v2/Users?filter=givenName sw "Google" and familyName sw "User" HTTP/1.1
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token}
```

*Response Body:*

```
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 8,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "id": "dd525596-f8bb-45d8-83e5-02bbb3c501a1",
            "externalId": null,
            "meta": {
                "created": "2020-09-22T13:57:14.813+00:00",
                "lastModified": "2020-10-08T20:23:12.147+00:00",
                "location": "https://app-au.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1",
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "gsu2@onetrustsso.com",
            "name": {
                "familyName": "User",
                "givenName": "Google"
            },
            "userType": "Internal",
            "active": true,
            "groups": [
                {
                    "value": "444fd8af-e1ee-4742-b1af-94165a8c28c6:4a3227b7-a05f-423c-8ab0-307aa16a12b2",
                    "display": "Assessments Manager - Org5"
                },
                {
                    "value": "16e476bc-727d-41ae-88b2-298de3c41291:058adecf-b998-4886-9f06-87e36e09b037",
                    "display": "Awareness Training Learner - Org6.1"
                },
                {
                    "value": "7adac9e4-b3e4-4221-83d1-f174134b5445:6e051cbf-1e3b-4815-8216-50e2a0518438",
                    "display": "Audit Manager - Azure AD"
                }
            ],
            "emails": [
                {
                    "value": "gsu2@onetrustsso.com",
                    "display": "gsu2@onetrustsso.com",
                    "primary": true,
                    "type": "work"
                }
            ],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "businessUnit": null,
                "division": null,
                "employeeId": null,
                "officeLocation": null,
                "department": null,
                "manager": {
                    "value": null,
                    "displayName": null,
                    "$ref": "https://trial.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1"
                },
                "jobTitle": null
            }
        }
    ]
}
```

Note that the above response contains the user's `id` which is `dd525596-f8bb-45d8-83e5-02bbb3c501a1`. Additionally, the response also returns the groups that the user is currently part of. The groups are:

* Assessments Manager - Org5
* Awareness Training Learner - Org6.1
* Audit Manager - Test Org

The naming convention of a group is in the format `{Role} - {Organization}`. Therefore, it can be inferred that the user has the `Assessments Manager` role in the organization `Org5`, the `Awareness Training Learner` role in the organization `Org6.1`, and the `Audit Manager` role in the organization `Test Org`.

## Step 2: Obtaining the Group's unique Id `groupId`

The [GET /Groups](/onetrust/reference/listgroupsusingget) endpoint can be used to retrieve the list of groups from the account.

SCIM filtering is not currently supported for Groups. By using custom scripts, the required role and organization combination can be obtained from the response of the above API.

*Example Request:*

```
GET /api/scim/v2/Groups?startIndex=1&count=1 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/x-www-form-urlencoded
```

*Response Body:*

```
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 130,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
            "externalId": null,
            "meta": {
                "created": "2020-10-08T20:20:41.213+00:00",
                "lastModified": "2020-10-16T00:28:10.973+00:00",
                "location": "https://trial.onetrust.com/api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group",
                "urn:ietf:params:scim:schemas:onetrust:Group"
            ],
            "displayName": "Site Admin - Azure AD",
            "members": [],
            "urn:ietf:params:scim:schemas:onetrust:Group": {
                "category": "Azure AD",
                "description": "Site Admin has access to this Azure AD"
            }
        }
    ]
}
```

Note that the above response contains the group's `groupId` which is `444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438`.

## Step 3: Adding a new role/organization to the user

The [PATCH /Groups/{groupId}](/onetrust/reference/updategroupmembersusingpatch) endpoint can be used to add a user to a group. The user will then get the group's respective Role and Organization.

*Example Request:*

```
PATCH /api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/json
```

*Request Body:*

```
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1"
        }
      ]
    }
  ]
}
```

*Response Body:*

```
{
    "id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
    "externalId": null,
    "meta": {
        "created": "2020-10-08T20:21:05.133+00:00",
        "lastModified": "2020-10-08T20:21:05.133+00:00",
        "location": "https://trial.onetrust.com/api/scim/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
        "resourceType": "Group"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:onetrust:Group"
    ],
    "displayName": "Site Admin - Test Org",
    "members": [
        {
            "value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1",
            "type": "User",
            "$ref": "https://trial.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1"
        }
    ],
    "urn:ietf:params:scim:schemas:onetrust:Group": {
        "category": "Azure AD",
        "description": "Site Admin has access to this Test Org"
    }
}
```

## Step 4: Remove an existing role/organization from the user

The [PATCH /Groups/{groupId}](/onetrust/reference/updategroupmembersusingpatch) endpoint can be used to remove a user from a group.

*Example Request:*

```
PATCH /api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/json
```

*Request Body:*

```
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        {
          "value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1"
        }
      ]
    }
  ]
}
```

*Response Body:*

```
{
    "id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
    "externalId": null,
    "meta": {
        "created": "2020-10-08T20:21:05.133+00:00",
        "lastModified": "2020-10-08T20:21:05.133+00:00",
        "location": "https://trial.onetrust.com/api/scim/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
        "resourceType": "Group"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:onetrust:Group"
    ],
    "displayName": "Site Admin - Test Org",
    "members": [],
    "urn:ietf:params:scim:schemas:onetrust:Group": {
        "category": "Test Org",
        "description": "Site Admin has access to this Test Org"
    }
}
```