Managing and searching for user accounts
Once you create your user pool, you can view and manage users using the AWS Management Console, as well as the AWS Command Line Interface or the Amazon Cognito API. This topic describes how you can view and search for users using the AWS Management Console.
Viewing user attributes
Use the following procedure to view user attributes in the Amazon Cognito console.
Resetting a user's password
Use the following procedure to reset a user's password in the Amazon Cognito console.
Searching user attributes
If you have already created a user pool, you can search from the Users panel in the AWS Management Console. You can also use the Amazon Cognito ListUsers API, which accepts a Filter parameter.
You can search for any of the following standard attributes. Custom attributes are not searchable.
-
username (case-sensitive)
-
email
-
phone_number
-
name
-
given_name
-
family_name
-
preferred_username
-
cognito:user_status (called Status in the Console) (case-insensitive)
-
status (called Enabled in the Console) (case-sensitive)
-
sub
You can also list users with a client-side filter. The server-side filter matches no
more than 1 attribute. For advanced search, use a client-side filter with the
--query
parameter of the list-users
action in the AWS Command Line Interface.
When you use a client-side filter, ListUsers returns a paginated list of zero or more users.
You can receive multiple pages in a row with zero results. Repeat the query with each
pagination token that is returned until you receive a null pagination token value, then
review the combined result.
For more information about server-side and client-side filtering, see Filtering AWS CLI output in the AWS Command Line Interface User Guide.
Searching for users with the AWS Management Console
If you have already created a user pool, you can search from the Users panel in the AWS Management Console.
AWS Management Console searches are always prefix ("starts with") searches.
Searching for
users with the ListUsers
API
To search for users from your app, use the Amazon Cognito ListUsers API. This API uses the following parameters:
-
AttributesToGet
: An array of strings, where each string is the name of a user attribute to be returned for each user in the search results. If the array is empty, all attributes are returned. -
Filter
: A filter string of the form "AttributeName
Filter-Type
"AttributeValue
"". Quotation marks within the filter string must be escaped using the backslash (\
) character. For example,"family_name = \"Reddy\""
. If the filter string is empty,ListUsers
returns all users in the user pool.-
AttributeName
: The name of the attribute to search for. You can only search for one attribute at a time.Note You can only search for standard attributes. Custom attributes are not searchable. This is because only indexed attributes are searchable, and custom attributes cannot be indexed.
-
Filter-Type
: For an exact match, use=
, for example,given_name = "Jon"
. For a prefix ("starts with") match, use^=
, for example,given_name ^= "Jon"
. -
AttributeValue
: The attribute value that must be matched for each user.
-
-
Limit
: Maximum number of users to be returned. -
PaginationToken
: A token to get more results from a previous search. Amazon Cognito expires the pagination token after one hour. -
UserPoolId
: The user pool ID for the user pool on which the search should be performed.
All searches are case-insensitive. Search results are sorted by the attribute named by the
AttributeName
string, in ascending order.
Examples of
using the ListUsers
API
The following example returns all users and includes all attributes.
{ "AttributesToGet": [], "Filter": "", "Limit": 10, "UserPoolId": "us-east-1_samplepool" }
The following example returns all users whose phone numbers start with "+1312" and includes all attributes.
{ "AttributesToGet": [], "Filter": "phone_number ^= \"+1312\"", "Limit": 10, "UserPoolId": "us-east-1_samplepool" }
The following example returns the first 10 users whose family name is "Reddy". For each user, the search results include the user's given name, phone number, and email address. If there are more than 10 matching users in the user pool, the response includes a pagination token.
{ "AttributesToGet": [ "given_name", "phone_number", "email" ], "Filter": "family_name = \"Reddy\"", "Limit": 10, "UserPoolId": "us-east-1_samplepool" }
If the previous example returns a pagination token, the following example returns the next 10 users that match the same filter string.
{ "AttributesToGet": [ "given_name", "phone_number", "email" ], "Filter": "family_name = \"Reddy\"", "Limit": 10, "PaginationToken": "pagination_token_from_previous_search", "UserPoolId": "us-east-1_samplepool" }