# Generic SCIM Endpoint - Update Group

The Update Group endpoint updates the requested role. Group patching is the most complex operation currently supported in the StrongDM SCIM API.

### Request

#### Endpoint

`/provisioning/generic/v2/Groups/<ID>`

#### HTTP method

`PATCH`

#### Path variables

| Variable | Requirement | Description | Notes                                     | Example   |
| -------- | ----------- | ----------- | ----------------------------------------- | --------- |
| `<ID>`   | Required    | Role ID     | Returns a 404 if the role ID is not found | `r-00001` |

#### Request body attributes

| Attribute    | Description                                                                                                                                                                                                                            | Notes                                                                                                                                                                                                                                                | Example                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `Operations` | Array of objects including subattributes `op`, `path`, and `value`; the value provided for `op` indicates what Patch operation will be performed; possible values for `value` are `id` (user ID) and `displayName` (the new role name) | Returns a 400 if the `displayName` provided is empty; returns a 404 if user IDs are not found; ignores the request if a user ID to be removed from the role is not in the role, or if a user ID to be removed from the role does not match any users | `[{"op": "replace", "value": {"id": "r-274512e66171c631", "displayName": "newName"}}]` |
| `schemas`    | Schema URI for representing groups                                                                                                                                                                                                     | Include the value as indicated in the example.                                                                                                                                                                                                       | `["urn:ietf:params:scim:api:messages:2.0:PatchOp"]`                                    |

#### Potential Patch operations

* Add members to the role:

  `{"op": "add", "path": "members", "value": [{"value":"a-0001","display":"myUser@example.test"}]}`
* Update the role's name:

  `{"op": "replace", "value": {"displayName: "newName"}}`
* Replace the members assigned to the role by removing all existing members and setting it to a new set of members:

  `{"op": "replace", "path": "members", "value": [{"value":"a-0001","display":"myUser@example.test"}]}`
* Remove role members by ID:

  `{"op": "remove", "path": "members[value eq "a-0001"]}`

### Response Codes

| Code | Description                                                                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 204  | The result of all Patch operations does not change the role.                                                                                                                                                                                                         |
| 400  | The request body does not match one of the example formats (in some cases, additional fields to those detailed may be allowed, but they are ignored). A 400 can also mean a filter other than `members[value eq "userID"]` was provided to be removed from the role. |

### Example Requests and Responses

#### Example request and response to set a name

`PATCH /provisioning/generic/v2/Groups/r-274512e66171c631`

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "id": "r-274512e66171c631",
        "displayName": "newName"
      }
    }
  ]
}
```

**Response:**

```json
{
  "displayName": "newName",
  "id": "r-274512e66171c631",
  "members": [],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/r-274512e66171c631"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
```

#### Example request and response to set a member

`PATCH /provisioning/generic/v2/Groups/r-3b084f5b6171c6ce`

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "members",
      "value": [
        {
          "value": "a-1717153b6171c6ce",
          "display": "myUser@example.test"
        }
      ]
    }
  ]
}
```

**Response:**

```json
{
  "displayName": "RoleName",
  "id": "r-3b084f5b6171c6ce",
  "members": [
    {
      "display": "userEmail@example.test",
      "value": "a-1717153b6171c6ce"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/r-3b084f5b6171c6ce"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
```

#### Example request to remove a member

`PATCH /provisioning/generic/v2/Groups/r-2792813a6171c916`

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"a-4fa1a3466171c916\"]"
    }
  ]
}
```

**Response:**

```json
{
  "displayName": "RoleName",
  "id": "r-2792813a6171c916",
  "members": [],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/r-2792813a6171c916"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
```