Links

Admin API Examples

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.
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.
Schema:
auditLogs(
first: Int
last: Int
userIDs: [ID!]
sortDirection: SortDirection
before: String
after: String
rangeFrom: DateTime
rangeTo: DateTime
activityTypes: [AuditLogActivityType!]
): AuditLogConnection
Example:
Query
Response
query {
auditLogs(first: 4) {
edges {
node {
id
activityType
createdAt
}
}
}
}
{
"data": {
"auditLogs": {
"edges": [
{
"node": {
"activityType": "USER_AUTHENTICATED",
"createdAt": "2023-09-11T09:23:51Z",
"id": "QXVkaXRMb2c6MDAwMDAwMDAwMDA0ZDVjOQ"
}
}
]
}
}
}

1.2. users

You can use this query to fetch all registered users on your application. The users query returns a list of type User.
Schema:
users(
first: Int
last: Int
searchKeyword: String
sortBy: UserSortBy
sortDirection: SortDirection
before: String
after: String
): UserConnection
Example:
Query
Response
query {
users(first: 2) {
edges {
node {
id
standardAttributes
}
}
}
}
{
"data": {
"users": {
"edges": [
{
"node": {
"id": "VXNlcjo4ZGM4ZDgyjjkoKA0LTRjZGEtODZiOC03OTY4MGUwYzA5OGM",
"standardAttributes": {
"email": "[email protected]",
"email_verified": true,
"family_name": "John",
"given_name": "Doe",
"updated_at": 1686820949
}
}
},
{
"node": {
"id": "VXNlcjplMzA3OTAyaxKJuILTRjMjQtOTFjMS1jMmNkNjNhNmE0YWY",
"standardAttributes": {
"email": "[email protected]",
"email_verified": true,
"family_name": "Eliano",
"given_name": "Don",
"updated_at": 1694359032
}
}
}
]
}
}
}

1.3. node

A node represents a single object of different Types. The node query allows you to query a single object using the node ID. You learn more about node ID here: https://docs.authgear.com/reference/apis/admin-api/node-id.
Schema:
node(id: ID!): Node
Example:
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.
Query
Response
query {
node(id: "QXVkaXRMb2c6MDAwHJKwMDAwMDA0ZDViOQ") {
id
... on AuditLog {
id
activityType
createdAt
}
}
}
{
"data": {
"node": {
"activityType": "USER_AUTHENTICATED",
"createdAt": "2023-09-11T09:23:51Z",
"id": "QXVkaXRMb2c6MDAwHJKwMDAwMDA0ZDViOQ"
}
}
}

1.4. nodes

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.
Schema:
nodes(ids: [ID!]!): [Node]!
Example:
Query
Response
query {
nodes(ids: ["<NODE ID1>","<NODE ID2>"]) {
id
... on AuditLog {
id
activityType
createdAt
}
}
}
{
"data": {
"nodes": [
{
"activityType": "USER_AUTHENTICATED",
"createdAt": "2023-09-11T09:23:51Z",
"id": "QXKytXRMb4n6MDAwMDAwMDAwMDA0ZDVjUK"
},
{
"activityType": "USER_PROFILE_UPDATED",
"createdAt": "2023-09-14T06:57:27Z",
"id": "QXVkaXABb7c6MDAwMDAwMDAwMDA0ZGKkZA"
}
]
}
}

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.
Schema:
anonymizeUser(input: AnonymizeUserInput!): AnonymizeUserPayload!
Example:
Query
Response
mutation {
anonymizeUser(input: {userID: "<ENCODED USER ID>"}) {
anonymizedUserID
}
}
{
"data": {
"anonymizeUser": {
"anonymizedUserID": "XYQlcjo4ZGM4ZDg5OC1jNjA0ERRjZGEtODZiOC134TY4MGUwYzA5OGM"
}
}
}

2.2. createIdentity

The createIdentity mutation creates a new identity for a user.
Schema:
createIdentity(input: CreateIdentityInput!): CreateIdentityPayload!
Example:
Query
Response
mutation {
createIdentity(input: {userID: "<ENCODED USER ID>", definition: {loginID: {key: "email", value: "[email protected]"}}, password: "@x1ujD-9$"}) {
identity {
id
claims
}
}
}
{
"data": {
"createIdentity": {
"identity": {
"claims": {
"email": "[email protected]",
"https://authgear.com/claims/login_id/key": "email",
"https://authgear.com/claims/login_id/original_value": "[email protected]",
"https://authgear.com/claims/login_id/type": "email",
"https://authgear.com/claims/login_id/value": "[email protected]"
},
"id": "SWRlbnRpdHk6YjHiZGVhNjctABCwMy00OWU2LWIyOTMtNTIwMGU3KKUkMTBl"
}
}
}
}

2.3. createUser

The createUser mutation makes it possible to create a new user account from the Admin API.
Schema:
createUser(input: CreateUserInput!): CreateUserPayload!
Example:
Query
Response
mutation {
createUser(input: {definition: {loginID: {key: "email", value: "[email protected]"}}, password:"my$ecurepa55"}) {
user{
id
standardAttributes
}
}
}
{
"data": {
"createUser": {
"user": {
"id": "VXNlciklODRkMzdjZi1hZDQ5LTRiZDItOTMzZJ2tOGY1YThlYjc34RE",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694713743
}
}
}
}
}

2.4. deleteAuthenticator

This mutation deletes an authenticator for a specific user.
Schema:
deleteAuthenticator(input: DeleteAuthenticatorInput!): DeleteAuthenticatorPayload!
Example:
Query
Response
mutation {
deleteAuthenticator(input: {authenticatorID: "<ENCODED AUTHENTICATOR ID>"}) {
user {
authenticators {
edges {
node {
id
}
}
}
}
}
}
{
"deleteAuthenticator": {
"user": {
"authenticators": {
"edges": [
{
"node": {
"id": "QXV0aGVudGljYXRvcjpkGHczOGM0Yy0yNmY2LTQyOWMtODc0OS1kYTA3NjYxZjE0ABC"
}
}
]
}
}
}
}

2.5. deleteAuthorization

You can use the deleteAuthorization mutation to delete an existing authorization for a user.
Schema:
deleteAuthorization(input: DeleteAuthorizationInput!): DeleteAuthorizationPayload!
Example:
Query
Response
mutation {
deleteAuthorization(input: {authorizationID: "<ENCODED AUTHORIZATION ID>"}) {
user {
authorizations {
edges {
node {
id
}
}
}
}
}
}
{
"deleteAuthorization": {
"user": {
"authorizations": {
"edges": [
{
"node": {
"id": "QXV0aG9yaXphdGlvbjpkHFczOGM0Yy0yNmY2LTQyOWMtODc0OS1kYTA3NjYxZjE0EFG"
}
}
]
}
}
}
}

2.6. deleteIdentity

The deleteIdentity mutation deletes the identity of a user.
Schema:
deleteIdentity(input: DeleteIdentityInput!): DeleteIdentityPayload!
Example:
Query
Response
mutation {
deleteIdentity(
input: {identityID: "<ENCODED IDENTITY ID>"}) {
user {
identities {
edges {
node {
id
}
}
}
}
}
}
{
"data": {
"deleteIdentity": {
"user": {
"identities": {
"edges": [
{
"node": {
"id": "SWRlbgsgdggGj7776JJkDc1My00ZTM2LWEyNTktZjg0ZjUyOER4NWJi"
}
}
]
}
}
}
}
}

2.7. deleteUser

This mutation allows you to delete a specific user using the Admin API.
Schema:
deleteUser(input: DeleteUserInput!): DeleteUserPayload!
Example:
Query
Response
mutation {
deleteUser(input: { userID: "<ENCODED USER ID>"}) {
deletedUserID
}
}
{
"data": {
"deleteUser": {
"deletedUserID": "VXNxcjowOKKcMzdjZi1hZDQ5LTRiZDItOTMzZC0yOGY1YThlYja86DQ"
}
}
}

2.8. generateOOBOTPCode

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.
Schema:
generateOOBOTPCode(input: GenerateOOBOTPCodeInput!): GenerateOOBOTPCodePayload!
Example:
Query
Response
mutation {
generateOOBOTPCode(input: {purpose: LOGIN, target: "[email protected]"}) {
code
}
}
{
"data": {
"generateOOBOTPCode": {
"code": "552660"
}
}
}

2.9. resetPassword

The resetPassword mutation lets you rest a user's password from the Admin API.
Schema:
resetPassword(input: ResetPasswordInput!): ResetPasswordPayload!
Example:
Query
Response
mutation {
resetPassword(input: {userID: "<ENCODED USER ID>", password: "n3w-p4$s"}) {
user {
id
standardAttributes
}
}
}
{
"data": {
"resetPassword": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694742340
}
}
}
}
}

2.10. revokeAllSessions

With the revokeAllSessions mutation, you can revoke all sessions for a specific user.
Schema:
revokeAllSessions(input: RevokeAllSessionsInput!): RevokeAllSessionsPayload!
Example:
Query
Response
mutation {
revokeAllSessions(input: {userID: "<ENCODED USER ID>"}) {
user {
id
standardAttributes
}
}
}
{
"data": {
"revokeAllSessions": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694742340
}
}
}
}
}

2.11. revokeSession

This mutation revokes a specific user session. You can specify the session using the session ID.
Schema:
revokeSession(input: RevokeSessionInput!): RevokeSessionPayload!
Example:
Query
Response
mutation {
revokeSession(input: {sessionID: "<ENCODED SESSION ID>"}) {
user {
id
standardAttributes
}
}
}
{
"data": {
"revokeSession": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694742340
}
}
}
}
}

2.12. scheduleAccountAnonymization

The scheduleAccountAnonymization mutation provides a means to schedule a user account anonymization from the Admin API.
Schema:
scheduleAccountAnonymization(input: ScheduleAccountAnonymizationInput!): ScheduleAccountAnonymizationPayload!
Example:
Query
Response
mutation {
scheduleAccountAnonymization(input: {userID: "<ENCODED USER ID>"}) {
user {
id
standardAttributes
}
}
}
{
"data": {
"scheduleAccountAnonymization": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694742340
}
}
}
}
}

2.13. scheduleAccountDeletion

The scheduleAccountDeletion mutation provides a means to schedule a user account deletion from the Admin API.
Schema:
scheduleAccountDeletion(input: ScheduleAccountDeletionInput!): ScheduleAccountDeletionPayload!
Example:
Query
Response
mutation {
scheduleAccountDeletion(input: {userID: "<ENCODED USER ID>"}) {
user {
id
standardAttributes
}
}
}
{
"data": {
"scheduleAccountDeletion": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"standardAttributes": {
"email": "[email protected]",
"email_verified": false,
"updated_at": 1694742340
}
}
}
}
}

2.14. sendResetPasswordMessage

You can send a password reset message to a user from the Admin API using the sendResetPasswordMessage mutation.
Schema:
sendResetPasswordMessage(input: SendResetPasswordMessageInput!): Boolean
Example:
Query
Response
mutation {
sendResetPasswordMessage(input: {loginID: "<USER LOGIN ID LIKE EMAIL>"})
}
{
"data": {
"sendResetPasswordMessage": null
}
}

2.15. setDisabledStatus

The setDisabledStatus mutation enables you to enable or disable a user's account.
Schema:
setDisabledStatus(input: SetDisabledStatusInput!): SetDisabledStatusPayload!
Example:
Query
Response
mutation {
setDisabledStatus(input: {userID: "<ENCODED USER ID>", isDisabled: true, reason: "Test"}) {
user {
id
isDeactivated
}
}
}
{
"data": {
"setDisabledStatus": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"isDeactivated": false
}
}
}
}

2.16. setVerifiedStatus

You can use the setVerifiedStatus mutation to set a user as verified and unveried from the Admin API.
Schema:
setVerifiedStatus(input: SetVerifiedStatusInput!): SetVerifiedStatusPayload!
Example:
Query
Response
mutation {
setVerifiedStatus(input: {userID: "<ENCODED USER ID>", claimName: "email", claimValue: "[email protected]", isVerified: true}) {
user {
id
verifiedClaims {
name
value
}
}
}
}
{
"data": {
"setVerifiedStatus": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"verifiedClaims": [
{
"name": "email",
"value": "[email protected]"
}
]
}
}
}
}

2.17. unscheduleAccountAnonymization

This mutation allows you to cancel a previously scheduled mutation.
Schema:
unscheduleAccountAnonymization(input: UnscheduleAccountAnonymizationInput!): UnscheduleAccountAnonymizationPayload!
Example:
Query
Response
mutation {
unscheduleAccountAnonymization(input: {userID: "<ENCODED USER ID>"}) {
user {
id
}
}
}
{
"data": {
"unscheduleAccountAnonymization": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse"
}
}
}
}

2.18. unscheduleAccountDeletion

This mutation allows you to cancel a previously scheduled deletion.
Schema:
unscheduleAccountDeletion(input: UnscheduleAccountDeletionInput!): UnscheduleAccountDeletionPayload!
Example:
Query
Response
mutation {
unscheduleAccountDeletion(input: {userID: "<ENCODED USER ID>"}) {
user {
id
}
}
}
{
"data": {
"unscheduleAccountDeletion": {
"user": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse"
}
}
}
}

2.19. updateIdentity