In this section of the Authgear documentation, you'll learn about all the GraphQL queries and mutations the Admin API supports.
Authgear provides a GraphQL API that you can use to manage users and other resources right from your application or using the GraphiQL Explorer in Authgear Portal > Advanced > Admin API.
The following section shows a detailed description and examples of supported queries and mutations.
1. Queries
1.1. auditLogs
The auditLogs query returns a list of all activities (logs) from the audit log.
You can specify different object types to the node query to fetch an item of that type. Examples of node Types include User, AuditLog, Session, Authenticator, Authorization, and Identity.
The following example uses the AuditLog node type.
The nodes query returns a list of nodes. This works similarly to the node query except that instead of supplying a single ID, you can provide a list of IDs for the objects you are querying for.
The groups query returns a list of all groups in an Authgear project. It will return nothing if no group has been created yet. Groups can be a field in the roles query.
{"data": {"groups": {"edges": [ {"cursor":"b2Zmc2V0OjA","node": {"description":"Staff members with super admin permissions","id":"R3JvdXA6OTU4YTA2ODIXRMb4n6MDAwMDAwMDAwMDA0ZDVjUKx","key":"admin_staff" } }, {"cursor":"b2Zmc2V0OjE","node": {"description":"Group for quickly applying team_member role to batch users.","id":"R3JvdXA6XRMb4n6MDAwMDAwMDAwMDA0ZDVjUKJl","key":"regular_staff" } } ] } }}
1.6 roles
You can use this query to get all the roles available in an Authgear project. The roles query will return nothing if no roles have been created for the Authgear project. Roles can also be a field in the node of the groups query. See Manage Users Roles and Groups to learn more about roles and groups.
{"data": {"roles": {"edges": [ {"cursor":"b2Zmc2V0OjA","node": {"description":"Leads a specific department where they also work.","groups": {"edges": [] },"id":"Um9sZTozMjc5NWRiNhOTgtOTzMzZkZGNi1hOWVkLTE2MC0RlOWFkMTM","key":"department_lead" } }, {"cursor":"b2Zmc2V0OjE","node": {"description":"Regular staff working in a specific department.","groups": {"edges": [ {"node": {"key":"regular_staff" } } ] },"id":"Um9sZToyMjc5NWRiNhOTgtOTzMzZkZGNi1hOWVkLTE2MC0RlOWFkZTA","key":"team_member" } } ] } }}
2. Mutations
With mutations, you can modify data from your application using the Admin API GraphQL. For example, you can use mutation to update
2.1. anonymizeUser
Calling this mutation will change a specific user account to an anonymous account. In other words, this query anonymizes a specific user. This action will delete the user's data like name and gender.
Calling the generateOOBOTPCode mutation will generate a new OOB OTP Code for a user. This mutation allows you to specify the purpose and target of the OTP as input.
mutation {
setVerifiedStatus(input: {userID: "<ENCODED USER ID>", claimName: "email", claimValue: "user@gmail.com", isVerified: true}) {
user {
id
verifiedClaims {
name
value
}
}
}
}
You can use this mutation to update an existing user's details. You can update standard attributes such as email and phone for the user. Or you can modify custom fields using the customAttributes argument.
For this updateUser example, we will be updating the standard attributes for a user. The first thing to do is to extract all the current values of the user's standard attributes into a variable. Then, add new fields or modify existing fields in the variable with new values.
Note: It is important to include the current values of the fields that you don't wish to update but still want to keep. The Admin API will delete any existing fields you omit in the variable.
The following block of code shows an example variable. If you're using GraphiQL, simply create the variable in the variable tab of GraphiQL like this:
The following example shows how to update custom attributes.
Note: You must have created the custom attributes you wish to update in Authgear Portal > User Profile > Custom Attributes.
Create a variable and extract the current custom attributes into it. Modify the values of the attributes you wish to update or add new attributes.
Note: Again, it is important to include the current values of the fields that you don't wish to update but still want to keep. The Admin API will delete any existing fields you omit in the variable.
The following block of code shows an example of the variable. You can set the variable in the variable tab of GraphiQL.
{
"customAttributes": {
"town": "Lagos"
}
}
mutation ($customAttributes: UserCustomAttributes) {
updateUser(input: {userID: "<ENCODED USER ID>", customAttributes: $customAttributes}) {
user {
id
customAttributes
}
}
}
mutation {
createGroup(input: {key: "test_group", name: "Test group", description: "This is a test group created using the Admin API"}) {
group {
id
}
}
}
Note: The value of key can not be empty, must be between 1 and 40 characters long, accepted characters are [a-zA-Z0-9:_] and the prefix authgear: is reserved for Authgear internal use.
2.22 createRole
You can use this mutation to add a new access management role to your Authgear application.
Note: The value of key can not be empty, must be between 1 and 40 characters long, accepted characters are [a-zA-Z0-9:_] and the prefix authgear: is reserved for Authgear internal use.
2.23 addRoleToGroups
Use this mutation to add a role to one or more groups in a single operation.