Retrieving users using Admin API
Overview and examples for the getUser/getUsers queries
The getUser and getUsers queries are a collection of Admin API queries for getting details about a single user or multiple users using specific attributes as the search key and in real-time.
Queries in the collection vary by the type of attribute they support as a search key. The queries are:
getUsersByStandardAttribute(attributeName: String!, attributeValue: String!)
getUserByLoginID(loginIDKey: String!, loginIDValue: String!)
getUserByOAuth(oauthProviderAlias: String!, oauthProviderUserID: String!)
Difference Between Users query and the getUser/getUsers queries
The users
query is another type of query used to retrieve users. In the following section, we'll discuss the difference between the getUser/getUsers queries and the users
query.
Immediately Consistent: the getUser and getUsers queries search the database directly for users while the
users
query depends on a search index. As a result, theusers
query may not return details about a recently edited user, while getUser and getUsers queries are immediately consistent.Exact Match: the getUser and getUsers queries only return a result that is an exact match. While calling the
users
query may return users when there is a partial match of a user's email, phone number, or name.Specific attribute: with the getUser and getUsers queries, you need to specify to retrieve the user by their email, username, or phone number. While the
users
query uses a singlesearchKeyword
field.
The following section contains details and examples for each query in the getUser and getUsers queries:
1. getUsersByStandardAttribute
The getUsersByStandardAttribute
query provides a way to retrieve users using a predefined standard attribute as the search key. The following are the standard attributes (attributeName
) that you can use:
email
preferred_username
phone_number
You can use the getUsersByStandardAttribute
query to get details for a user that registered with a loginID
or OAuth connection. For example, you can use the email
field in the standard attribute as a search key to find a user who linked an email address from an OAuth connection or registered using the email and password login method.
Schema:
getUsersByStandardAttribute(
attributeName: String!
attributeValue: String!
): [User!]!
Inputs:
attributeName
: The name of the standard attribute that will be used as the search key. The value can only be:email
,preferred_username
, orphone_number
.attributeValue
: The actual value for the user's standard attribute that you're using (attributeName
) as the search key. For example, the full email address of the user if you are usingemail
as the value forattributeName
.
Example:
query {
getUsersByStandardAttribute(attributeName: "email", attributeValue: "user@example.com") {
id,
standardAttributes
}
}
2. getUserByLoginID
Use the getUserByLoginID
query to retrieve details about a user using their loginID
as the search key. The following are the types of loginID
supported:
email
username
phone
Note: An email address linked to a user's account via social/enterprise login (OAuth) provider only can not be used as a search key in the getUserByLoginID query. Use getUsersByStandardAttribute instead to search for email addresses linked via OAuth provider only.
Schema:
getUserByLoginID(
loginIDValue: String!
loginIDKey: String!
): User
Inputs:
loginIDKey
: the value of this field should be the type of loginID associated with the user's account (email
,phone
orusername
).loginIDValue
: enter the exact value of the identity associated with the user's account. For example, the user's full email address if their identity isemail
. Forphone
, use the full phone number including the "+" sign and country code, e.g. +441234567890.
Example:
The following example shows a getUserByLoginID
query and a response when a user is found.
query {
getUserByLoginID(loginIDKey: "email", loginIDValue: "user@example.com") {
id,
standardAttributes
}
}
3. getUserByOAuth
The getUserByOAuth
query allows you to retrieve details about a user that linked an identity using a social/enterprise provider. For example, you can use the getUserByOAuth
query to search for a user that linked their account to Facebook using the User ID (sub) issued by Facebook OAuth provider as the search key.
Schema:
getUserByOAuth(
oauthProviderAlias: String!
oauthProviderUserID: String!
): User
Inputs:
oauthProviderAlias
: This is an identifier for each OAuth provider that can be set in Authgear portal via Authentication > Social / Enterprise Login. The default for value isgoogle
,facebook
,github
,apple
for respective social login providers.oauthProviderUserID
: The value for this field should be thesub
(User ID) returned by the OAuth provider. You can see the value of a user's oauthProviderUserID in theiroauthConnections.claims
under theid
field. See the official documentation for each OAuth provider to learn more about their sub. This page shows an example ofsub
from Facebook.
Example
query {
getUserByOAuth(oauthProviderAlias: "facebook", oauthProviderUserID: "1234567812730389") {
id,
oauthConnections {
claims
}
}
}
Last updated
Was this helpful?