---
updatedAt: 2026-05-12T09:59:46.000Z
---

# Update user associations

This operation updates the assets, groups, or clients associated with a particular user, as identified by their User ID.

# OpenAPI definition

```json
{
  "components": {
    "responses": {
      "BadRequestResponse": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            }
          }
        },
        "description": "BadRequestResponse indicates a request with invalid parameters"
      },
      "ForbiddenResponse": {
        "description": "ForbiddenResponse signals a request for a resource that does not exist or is not authorized"
      },
      "GenericError": {
        "description": "GenericError generic error"
      },
      "PatchUserResponse": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/userSwagger"
            }
          }
        },
        "description": "PatchUserResponse provides user information for a single requested user"
      },
      "UnauthorizedResponse": {
        "description": "UnauthorizedResponse signals an unauthorized API access"
      }
    },
    "schemas": {
      "AssociatedAsset": {
        "description": "AssociatedAsset holds information about an associated asset",
        "properties": {
          "assetID": {
            "format": "int64",
            "type": "integer"
          },
          "byClient": {
            "type": "boolean"
          },
          "byGroup": {
            "type": "boolean"
          },
          "byUser": {
            "type": "boolean"
          },
          "clientID": {
            "format": "int64",
            "type": "integer"
          },
          "directlyAssociatedRole": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "directlyAssociatedRoleName": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "AssociatedGroup": {
        "description": "AssociatedGroup holds information about an associated group",
        "properties": {
          "byClient": {
            "type": "boolean"
          },
          "clientID": {
            "format": "int64",
            "type": "integer"
          },
          "direct": {
            "type": "boolean"
          },
          "directlyAssociatedRole": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "directlyAssociatedRoleName": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "AssociatedRole": {
        "description": "AssociatedRole holds numeric id and name for roles associated with users",
        "properties": {
          "id": {
            "format": "int64",
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ClientAdmin": {
        "description": "ClientAdmin is the list of clients that a given user is admin for",
        "properties": {
          "clientID": {
            "format": "int64",
            "type": "integer"
          },
          "clientName": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "EmailFreq": {
        "description": "EmailFreq holds info about the users email frequency",
        "properties": {
          "daily": {
            "type": "boolean"
          },
          "monthly": {
            "type": "boolean"
          },
          "weekly": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "EmailPreferences": {
        "description": "EmailPreferences holds the email preference data for a user",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ErrorMessage": {
        "description": "ErrorMessage describes the error",
        "properties": {
          "code": {
            "format": "int64",
            "type": "integer"
          },
          "reason": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UserAssociationInput": {
        "description": "UserAssociationInput holds the request body details needed for updating a user's associations",
        "properties": {
          "op": {
            "description": "'op' is the desired association action. Valid values are *add* or *remove*.\n\nin: body",
            "type": "string"
          },
          "roleID": {
            "description": "'roleID' is the role ID to be used for this association.\nIf the *type* is *assignedAssets* or *assignedGroups* and *roleID* is omitted, *roleID* will default to the user's native role (usually Viewer).\nIf the *type* is *assignedClients*, the only supported *roleID* value is 1 (Admin).\n\nin: body",
            "format": "int64",
            "type": "integer"
          },
          "type": {
            "description": "'type' is the type of association to be done. Valid values are *assignedAssets*, *assignedGroups*, or *assignedClients*.\n\nin: body",
            "type": "string"
          },
          "values": {
            "description": "'values' are ID values corresponding to the objects to be associated\n\nin: body",
            "items": {
              "format": "int64",
              "type": "integer"
            },
            "type": "array"
          }
        },
        "required": [
          "op",
          "type",
          "values"
        ],
        "type": "object"
      },
      "userSwagger": {
        "description": "userSwagger is data returned when a single user is requested",
        "properties": {
          "associatedAssets": {
            "items": {
              "$ref": "#/components/schemas/AssociatedAsset"
            },
            "type": "array"
          },
          "associatedGroups": {
            "items": {
              "$ref": "#/components/schemas/AssociatedGroup"
            },
            "type": "array"
          },
          "associatedRoles": {
            "items": {
              "$ref": "#/components/schemas/AssociatedRole"
            },
            "type": "array"
          },
          "canDelete": {
            "type": "boolean"
          },
          "canEdit": {
            "type": "boolean"
          },
          "client": {
            "properties": {
              "id": {
                "format": "int64",
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "clientAdminList": {
            "items": {
              "$ref": "#/components/schemas/ClientAdmin"
            },
            "type": "array"
          },
          "createdBy": {
            "nullable": true,
            "type": "string"
          },
          "createdDate": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "dataPrivacy": {
            "type": "boolean"
          },
          "emailFrequency": {
            "$ref": "#/components/schemas/EmailFreq"
          },
          "emailPreferences": {
            "items": {
              "$ref": "#/components/schemas/EmailPreferences"
            },
            "type": "array"
          },
          "firstName": {
            "type": "string"
          },
          "id": {
            "format": "int64",
            "type": "integer"
          },
          "jobTitle": {
            "nullable": true,
            "type": "string"
          },
          "lastLogin": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "lastName": {
            "type": "string"
          },
          "mobile": {
            "nullable": true,
            "type": "string"
          },
          "phone": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "vulnEmails": {
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  },
  "info": {
    "license": {
      "name": "(c) Copyright 2022 WhiteHat Security"
    },
    "title": "Access Control Management API",
    "version": "2.0.0"
  },
  "openapi": "3.0.1",
  "paths": {
    "/api/users/{id}": {
      "patch": {
        "description": "This operation updates the assets, groups, or clients associated with a particular user, as identified by their User ID.",
        "operationId": "patchUserInputSwagger",
        "parameters": [
          {
            "description": "ID for user patch operations",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "int64",
              "type": "integer"
            },
            "x-go-name": "ID"
          },
          {
            "description": "Fields allows the user to specify optional fields returned in the user response\nSupported values:\n'client' returns client info for the user\n'associatedRoles' returns role ids and names assigned to the user\n'associatedCounts' returns the number of groups and assets assigned to the user\n'associatedAssets' returns the assetID, clientID, and how assets are associated with the user\n'associatedGroups' returns the group id, clientID, and how the groups are associated with the user\n'clientAdminList' returns the list of clients for which the user is an all sites admin",
            "explode": false,
            "in": "query",
            "name": "fields",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/UserAssociationInput"
                },
                "type": "array"
              }
            }
          },
          "description": "Body of the request holds the data to input when updating user group associations.\nThe user that is affected is not indicated here, but instead\nis specified in the id url parameter.",
          "required": true,
          "x-go-name": "Body"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PatchUserResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequestResponse"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedResponse"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "500": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "summary": "Update user associations",
        "tags": [
          "Access Control Management API v2.0"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://sentinel.whitehatsec.com/"
    }
  ],
  "tags": [
    {
      "name": "Access Control Management API v2.0"
    }
  ],
  "x-explorer-enabled": false,
  "x-readme": {
    "proxy-enabled": true
  }
}
```