> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Update a user

`PUT /api/web/v3/users/{id}`

Update the specified user. Caller requires the USERS:EDIT permission.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | Yes | string | The UUID of the user to be updated. |

## Request Body

Required.

### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "applyGracePeriod": {
      "type": "boolean",
      "description": "Indicates if the user is granted a new frozen grace period. This value is not used when creating a user. If provided, it will be ignored.",
      "example": true
    },
    "email": {
      "type": "string",
      "description": "The email address of this user.  This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  It must be set to use EMAIL OTP authentication and other features that require an email address.  To remove the existing value, set the value to an empty string.",
      "example": "johnsmith@organization.com"
    },
    "emailVerification": {
      "type": "boolean",
      "description": "Indicates if a verification email message should be sent to the user if the user now requires verification. The user's policy requiring user verification must also be enabled for the user. If not set, this value defaults to true.",
      "example": true
    },
    "externalId": {
      "type": "string",
      "description": "An optional external ID for this user.  This value can be used to track the external identity of an Identity as a Service user. To unset the external ID, specify an empty string."
    },
    "externalSource": {
      "type": "string",
      "description": "An optional value that describes the source when the user is synchronized from an external source. To unset the external source, specify an empty string."
    },
    "firstName": {
      "type": "string",
      "description": "The first name of this user.  This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  To remove the existing value, set the value to an empty string.",
      "example": "John"
    },
    "groups": {
      "type": "array",
      "description": "A list of group UUIDs to be assigned to this user.  If specified, these groups replace existing groups.",
      "items": {
        "type": "string",
        "description": "A list of group UUIDs to be assigned to this user.  If specified, these groups replace existing groups."
      }
    },
    "lastName": {
      "type": "string",
      "description": "The last name of this user.    This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  To remove the existing value, set the value to an empty string.",
      "example": "Smith"
    },
    "locale": {
      "type": "string",
      "description": "The locale of this user.  If not set, the default account locale will be used. To remove the existing value, set the value to an empty string.",
      "example": "en",
      "enum": [
        "da",
        "de",
        "en",
        "es",
        "fr",
        "it",
        "ja",
        "ko",
        "nl",
        "nb",
        "pl",
        "pt",
        "ru",
        "sv",
        "th",
        "tr",
        "zh-cn",
        "zh-tw"
      ]
    },
    "lock": {
      "type": "boolean",
      "description": "Indicates if all the user's authenticators are locked or not.",
      "example": true
    },
    "mobile": {
      "type": "string",
      "description": "The mobile number of this user.  This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  It must be set to use SMS OTP authentication.  To remove the existing value, set the value to an empty string.",
      "example": "+16138691234"
    },
    "oauthRoles": {
      "type": "array",
      "description": "A list of oauth role UUIDs to be assigned to this user.  If specified, these oauth roles replace existing oauth roles.",
      "items": {
        "type": "string",
        "description": "A list of oauth role UUIDs to be assigned to this user.  If specified, these oauth roles replace existing oauth roles."
      }
    },
    "organizations": {
      "type": "array",
      "description": "A list of organization UUIDs to be assigned to this user.  If specified, these organizations replace existing organizations.",
      "items": {
        "type": "string",
        "description": "A list of organization UUIDs to be assigned to this user.  If specified, these organizations replace existing organizations."
      }
    },
    "phone": {
      "type": "string",
      "description": "The phone number of this user.  This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  It must be set to use VOICE OTP authentication.  To remove the existing value, set the value to an empty string.",
      "example": "+16138691234"
    },
    "preferredOtpDelivery": {
      "type": "string",
      "description": "Preferred OTP delivery type (SMS, EMAIL or VOICE) or SYSTEM to use the system defined default.",
      "example": "SYSTEM",
      "enum": [
        "EMAIL",
        "SMS",
        "VOICE",
        "SYSTEM"
      ]
    },
    "preferredOtpDeliveryContactAttributes": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "description": "Preferred OTP delivery contact attribute for the given type (i.e., OTP_EMAIL, OTP_SMS, OTP_VOICE. An empty string means no override for that type).",
        "example": "{\"OTP_EMAIL\":\"Email\",\"OTP_SMS\":\"Personal Mobile\",\"OTP_VOICE\":\"default\"}"
      },
      "description": "Preferred OTP delivery contact attribute for the given type (i.e., OTP_EMAIL, OTP_SMS, OTP_VOICE. An empty string means no override for that type).",
      "example": {
        "OTP_EMAIL": "Email",
        "OTP_SMS": "Personal Mobile",
        "OTP_VOICE": "default"
      }
    },
    "registrationRequired": {
      "type": "boolean",
      "description": "Indicates whether self-registration is required. If not set when the user is created, this value defaults to true.",
      "example": true
    },
    "securityId": {
      "type": "string",
      "description": "The security ID of this user. The security ID is a unique value used to identity the user when performing smart card login to Microsoft Windows.",
      "example": "8c35d5f2-a18a-11ed-a8fc-0242ac120002"
    },
    "state": {
      "type": "string",
      "description": "The state of this user.  Only users in the ACTIVE state can perform authentication. If not set when the user is created, this value defaults to ACTIVE.",
      "example": "ACTIVE",
      "enum": [
        "ACTIVE",
        "INACTIVE"
      ]
    },
    "userAliases": {
      "type": "array",
      "description": "A list of user aliases for this user. Alias values must be unique with respect to the userId and other aliases of this user and other users.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The UUID of this user alias set when the user alias is created.",
            "example": "76234da-3cf2-4t6u-8d02-8234fdfc472"
          },
          "type": {
            "type": "string",
            "description": "The type of user alias. A value of USERID is used for an alias that will represent the actual user id value. A value of CUSTOM is used for aliases manually created by an administrator.  A value of DERIVED is defined for future use and should not be used at this time.",
            "enum": [
              "CUSTOM",
              "DERIVED",
              "USERID"
            ]
          },
          "userId": {
            "type": "string",
            "description": "The UUID of the user to which this user alias belongs.",
            "example": "42133ed4-3cf2-4t6u-8d02-8234fdfc472"
          },
          "value": {
            "type": "string",
            "description": "The value for the user alias.",
            "example": "some-alias"
          }
        },
        "description": "Specifies an alias for a particular user.",
        "title": "UserAlias"
      }
    },
    "userAttributeValues": {
      "type": "array",
      "description": "A list of user attribute values for this user.",
      "items": {
        "type": "object",
        "properties": {
          "editable": {
            "type": "boolean",
            "description": "A flag indicating if this user attribute value can be modified."
          },
          "id": {
            "type": "string",
            "description": "The UUID of this user attribute value set when the user attribute value is created.",
            "example": "76234da-3cf2-4t6u-8d02-8234fdfc472"
          },
          "lastUpdate": {
            "type": "string",
            "description": "The last time the attribute value was updated.",
            "format": "date-time",
            "example": "2019-02-19T13:15:27Z"
          },
          "userAttribute": {
            "required": [
              "mandatory",
              "name",
              "systemDefined",
              "unique"
            ],
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The UUID for this user attribute.  Generated when the user attribute is created."
              },
              "mandatory": {
                "type": "boolean",
                "description": "A flag indicating if users must have a value for this user attribute."
              },
              "name": {
                "type": "string",
                "description": "The name of this user attribute."
              },
              "systemDefined": {
                "type": "boolean",
                "description": "A flag indicating if this user attribute is one of the system defined user attributes."
              },
              "type": {
                "type": "string",
                "description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.",
                "example": "OTP_EMAIL",
                "enum": [
                  "NONE",
                  "OTP_EMAIL",
                  "OTP_SMS",
                  "OTP_VOICE",
                  "OTP_WECHAT",
                  "OTP_WHATSAPP"
                ]
              },
              "unique": {
                "type": "boolean",
                "description": "A flag indicating if this attribute is intended to be unique."
              }
            },
            "description": "Information about user attribute definitions.",
            "title": "UserAttribute"
          },
          "userAttributeId": {
            "type": "string",
            "description": "The UUID of the user attribute that defines this user attribute value.  The userAttributeId must be provided when creating or modifying a user attribute value.",
            "example": "76234da-3cf2-4t6u-8d02-8234fdfc472"
          },
          "userId": {
            "type": "string",
            "description": "The UUID of the user to which this user attribute value belongs.",
            "example": "John"
          },
          "value": {
            "type": "string",
            "description": "The value for the user attribute.",
            "example": "value"
          }
        },
        "description": "Specifies the value of a user attribute for a particular user.",
        "title": "UserAttributeValue"
      }
    },
    "userExtraAttributes": {
      "type": "array",
      "description": "A list of extra optional attributes for this user.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The UUID of this extra user attribute.",
            "readOnly": true,
            "example": "76234da-3cf2-4t6u-8d02-8234fdfc472"
          },
          "name": {
            "type": "string",
            "description": "The name for the extra user attribute.",
            "example": "some-attr-name"
          },
          "type": {
            "type": "string",
            "description": "Type of custom user attribute.",
            "example": "OTP_SMS",
            "enum": [
              "NONE",
              "OTP_EMAIL",
              "OTP_SMS",
              "OTP_VOICE",
              "OTP_WECHAT",
              "OTP_WHATSAPP"
            ]
          },
          "value": {
            "type": "string",
            "description": "The value for the extra user attribute.",
            "example": "some-value"
          }
        },
        "description": "Specifies an extra optional attribute for a particular user.",
        "title": "UserExtraAttribute"
      }
    },
    "userId": {
      "type": "string",
      "description": "The user ID for this user.  This value is required when creating the user, optional during update. The userId must be unique with respect to aliases of this user and the userId and aliases of all other users.",
      "example": "jsmith"
    },
    "userPrincipalName": {
      "type": "string",
      "description": "The user principal name of this user.  This value may or may not be required depending on configuration.  If it is required, it must be specified when creating the user.  If it is required, it must be specified when updating the user and a value is not currently set.  To remove the existing value, set the value to an empty string.",
      "example": "johnsmith@organization.com"
    },
    "verificationRequired": {
      "type": "boolean",
      "description": "Indicates whether verification is required. If not set when the user is created, this value defaults to true.",
      "example": true
    }
  },
  "description": "Attributes for the new user.",
  "title": "UserParms"
}
```

## Responses

### 200

Successful

### 400

Bad Request

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 401

Access denied

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 403

Forbidden

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 404

Not Found

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 409

Conflict

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

## Security

Requirements

```json
[
  {
    "AdminAPIAuthentication": [
      "USERS:EDIT"
    ]
  }
]
```