AdminUpdateUserAttributes
Note
This action might generate an SMS text message. Starting June 1, 2021, US telecom carriers
require you to register an origination phone number before you can send SMS messages
to US phone numbers. If you use SMS text messages in Amazon Cognito, you must register a
phone number with Amazon Pinpoint
If you have never used SMS text messages with Amazon Cognito or any other AWS service, Amazon Simple Notification Service might place your account in the SMS sandbox. In sandbox mode , you can send messages only to verified phone numbers. After you test your app while in the sandbox environment, you can move out of the sandbox and into production. For more information, see SMS message settings for Amazon Cognito user pools in the Amazon Cognito Developer Guide.
Updates the specified user's attributes. To delete an attribute from your user, submit the attribute in your API request with a blank value.
For custom attributes, you must prepend the custom:
prefix to the
attribute name.
This operation can set a user's email address or phone number as verified and
permit immediate sign-in in user pools that require verification of these attributes. To
do this, set the email_verified
or phone_number_verified
attribute to true
.
Note
Amazon Cognito evaluates AWS Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy.
Request Syntax
{
"ClientMetadata": {
"string
" : "string
"
},
"UserAttributes": [
{
"Name": "string
",
"Value": "string
"
}
],
"Username": "string
",
"UserPoolId": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- ClientMetadata
-
A map of custom key-value pairs that you can provide as input for any custom workflows that this action triggers.
You create custom workflows by assigning AWS Lambda functions to user pool triggers. When you use the AdminUpdateUserAttributes API action, Amazon Cognito invokes the function that is assigned to the custom message trigger. When Amazon Cognito invokes this function, it passes a JSON payload, which the function receives as input. This payload contains a
clientMetadata
attribute, which provides the data that you assigned to the ClientMetadata parameter in your AdminUpdateUserAttributes request. In your function code in AWS Lambda, you can process theclientMetadata
value to enhance your workflow for your specific needs.For more information, see Using Lambda triggers in the Amazon Cognito Developer Guide.
Note
When you use the
ClientMetadata
parameter, note that Amazon Cognito won't do the following:-
Store the
ClientMetadata
value. This data is available only to AWS Lambda triggers that are assigned to a user pool to support custom workflows. If your user pool configuration doesn't include triggers, theClientMetadata
parameter serves no purpose. -
Validate the
ClientMetadata
value. -
Encrypt the
ClientMetadata
value. Don't send sensitive information in this parameter.
Type: String to string map
Key Length Constraints: Minimum length of 0. Maximum length of 131072.
Value Length Constraints: Minimum length of 0. Maximum length of 131072.
Required: No
-
- UserAttributes
-
An array of name-value pairs representing user attributes.
For custom attributes, you must prepend the
custom:
prefix to the attribute name.If your user pool requires verification before Amazon Cognito updates an attribute value that you specify in this request, Amazon Cognito doesn’t immediately update the value of that attribute. After your user receives and responds to a verification message to verify the new value, Amazon Cognito updates the attribute value. Your user can sign in and receive messages with the original attribute value until they verify the new value.
To skip the verification message and update the value of an attribute that requires verification in the same API request, include the
email_verified
orphone_number_verified
attribute, with a value oftrue
. If you set theemail_verified
orphone_number_verified
value for anemail
orphone_number
attribute that requires verification totrue
, Amazon Cognito doesn’t send a verification message to your user.Type: Array of AttributeType objects
Required: Yes
- Username
-
The username of the user that you want to query or modify. The value of this parameter is typically your user's username, but it can be any of their alias attributes. If
username
isn't an alias attribute in your user pool, this value must be thesub
of a local user or the username of a user from a third-party IdP.Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern:
[\p{L}\p{M}\p{S}\p{N}\p{P}]+
Required: Yes
- UserPoolId
-
The ID of the user pool where you want to update user attributes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 55.
Pattern:
[\w-]+_[0-9a-zA-Z]+
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors.
- AliasExistsException
-
This exception is thrown when a user tries to confirm the account with an email address or phone number that has already been supplied as an alias for a different user profile. This exception indicates that an account with this email address or phone already exists in a user pool that you've configured to use email address or phone number as a sign-in alias.
HTTP Status Code: 400
- InternalErrorException
-
This exception is thrown when Amazon Cognito encounters an internal error.
HTTP Status Code: 500
- InvalidEmailRoleAccessPolicyException
-
This exception is thrown when Amazon Cognito isn't allowed to use your email identity. HTTP status code: 400.
HTTP Status Code: 400
- InvalidLambdaResponseException
-
This exception is thrown when Amazon Cognito encounters an invalid AWS Lambda response.
HTTP Status Code: 400
- InvalidParameterException
-
This exception is thrown when the Amazon Cognito service encounters an invalid parameter.
HTTP Status Code: 400
- InvalidSmsRoleAccessPolicyException
-
This exception is returned when the role provided for SMS configuration doesn't have permission to publish using Amazon SNS.
HTTP Status Code: 400
- InvalidSmsRoleTrustRelationshipException
-
This exception is thrown when the trust relationship is not valid for the role provided for SMS configuration. This can happen if you don't trust
cognito-idp.amazonaws.com
or the external ID provided in the role does not match what is provided in the SMS configuration for the user pool.HTTP Status Code: 400
- NotAuthorizedException
-
This exception is thrown when a user isn't authorized.
HTTP Status Code: 400
- ResourceNotFoundException
-
This exception is thrown when the Amazon Cognito service can't find the requested resource.
HTTP Status Code: 400
- TooManyRequestsException
-
This exception is thrown when the user has made too many requests for a given operation.
HTTP Status Code: 400
- UnexpectedLambdaException
-
This exception is thrown when Amazon Cognito encounters an unexpected exception with AWS Lambda.
HTTP Status Code: 400
- UserLambdaValidationException
-
This exception is thrown when the Amazon Cognito service encounters a user validation exception with the AWS Lambda service.
HTTP Status Code: 400
- UserNotFoundException
-
This exception is thrown when a user isn't found.
HTTP Status Code: 400
Examples
Example
The following example request sets the values of two attributes for
"testuser." The request also includes client metadata that the user pool passes
on in a CustomMessage_UpdateUserAttribute
Lambda trigger
event.
Sample Request
POST HTTP/1.1
Host: cognito-idp.us-west-2.amazonaws.com
X-Amz-Date: 20230613T200059Z
Accept-Encoding: gzip, deflate, br
X-Amz-Target: AWSCognitoIdentityProviderService.AdminCreateUser
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>
{
"UserAttributes": [
{
"Name": "custom:deliverables",
"Value": "project-111222"
},
{
"Name": "name",
"Value": "John"
}
],
"UserPoolId": "us-west-2_EXAMPLE",
"Username": "testuser",
"ClientMetadata": {
"MyTestKey": "MyTestValue"
}
}
Sample Response
HTTP/1.1 200 OK
Date: Tue, 13 Jun 2023 20:00:59 GMT
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
x-amzn-requestid: a1b2c3d4-e5f6-a1b2-c3d4-EXAMPLE11111
Connection: keep-alive
{}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: