Authgear
Start BuildingHomePortalCommunity
  • Authgear Overview
  • Get Started
    • Start Building
    • 5-Minute Guide
    • Single-Page App
      • JavaScript (Web)
      • React
      • Angular
      • Vue
    • Native/Mobile App
      • iOS SDK
      • Android SDK
        • Android Kotlin coroutine support
        • Android OKHttp Interceptor Extension (Optional)
      • Flutter SDK
      • React Native SDK
      • Ionic SDK
      • Xamarin SDK
      • Using Authgear without SDK (Client side)
    • Regular Web App
      • Express
      • Next.js
      • Python Flask App
      • Java Spring Boot
      • ASP.NET Core MVC
      • Laravel
      • PHP
    • Backend/API Integration
      • Validate JWT in your application server
      • Forward Authentication to Authgear Resolver Endpoint
    • AI Coding tools
      • Cursor/Windsurf
  • How-To Guides
    • Authenticate
      • Add Passkeys Login
      • Add WhatsApp OTP Login
      • Add Email Magic Link Login
      • Add Biometric Login
      • Add Anonymous Users
      • Add authentication to any web page
      • Enable Two-Factor Authentication (2FA)
      • How to Use the OAuth 2.0 State Parameter
      • Reauthentication
      • How to Use Social/Enterprise Login Providers Without AuthUI
      • Passwordless Login for Apple App Store Review
      • Setup local development environment for Cookie-based authentication
      • Forgot/Reset Password settings
      • Phone number validation
      • Set Password Expiry
    • Single Sign-on
      • App2App Login
      • Pre-authenticated URLs
      • SSO between Mobile Apps / Websites
      • Force Authgear to Show Login Page
      • Single Sign-On with OIDC
      • Single Sign-On with SAML
        • Use Authgear as SAML Identity Provider for Salesforce
        • Use Authgear as SAML Identity Provider for Dropbox
        • SAML Attribute Mapping
    • Social Login / Enterprise Login Providers
      • Social Login Providers
        • Connect Apps to Apple
        • Connect Apps to Google
        • Connect Apps to Facebook
        • Connect Apps to GitHub
        • Connect Apps to LinkedIn
        • Connect Apps to WeChat
      • Enterprise Login Providers
        • Connect Apps to Azure Active Directory
        • Connect Apps to Microsoft AD FS
        • Connect Apps to Azure AD B2C
      • Force Social/Enterprise Login Providers to Show Login Screen
    • Built-in UI
      • Branding in Auth UI
      • User Settings
      • Privacy Policy & Terms of Service Links
      • Customer Support Link
      • Custom Text
    • Custom UI
      • Authentication Flow API
      • Implement Authentication Flow API using Express
      • Implement Authentication Flow API using PHP
      • Add Custom Login/Signup UI to Native Apps
      • Manually Link OAuth Provider using Account Management API
      • Implement a custom account recovery UI using Authentication Flow API
    • Integrate
      • Add custom fields to a JWT Access Token
      • User Analytics by Google Tag Manager
      • Track User Before and After Signup
      • Custom domain
      • Custom Email Provider
      • Custom SMS Provider
        • Twilio
        • Webhook/Custom Script
    • Monitor
      • Audit Log For Users Activities
      • Audit Log for Admin API and Portal
      • Analytics
    • User Management
      • Account Deletion
      • Import Users using User Import API
      • Export Users using the User Export API
      • Manage Users Roles and Groups
      • How to Handle Password While Creating Accounts for Users
    • User Profiles
      • What is User Profile
      • Access User Profiles
      • Update User Profiles
      • Profile Custom Attributes
      • Update user profile on sign-up using Hooks
    • Events and Hooks
      • Event List
      • Webhooks
      • JavaScript / TypeScript Hooks
      • Only Allow Signups from Inside the Corporate Network using Hooks
    • Mobile Apps
      • Use SDK to make authorized API calls to backend
      • Force authentication on app launch
      • Customize the Login Pop-up / Disable the login alert box
    • Languages and Localization
    • Custom Email and SMS Templates
    • Directly accessing Authgear Endpoint
    • Migration
      • Bulk migration
      • Rolling migration
      • Zero-downtime migration
    • Troubleshoot
      • How to Fix SubtleCrypto: digest() undefined Error in Authgear SDK
      • How to Fix CORS Error
  • Concepts
    • Identity Fundamentals
    • Authgear use cases
    • User, Identity and Authenticator
  • Security
    • Brute-force Protection
    • Bot Protection
    • Non-HTTP scheme redirect URI
    • Password Strength
  • Reference
    • APIs
      • Admin API
        • Authentication and Security
        • API Schema
        • Admin API Examples
        • Using global node IDs
        • Retrieving users using Admin API
        • User Management Examples
          • Search for users
          • Update user's standard attributes
          • Update user's picture
          • Generate OTP code
      • Authentication Flow API
      • OAuth 2.0 and OpenID Connect (OIDC)
        • UserInfo
        • Supported Scopes
      • User Import API
      • User Export API
    • Tokens
      • JWT Access Token
      • Refresh Token
    • Glossary
    • Billing FAQ
    • Rate Limits
      • Account Lockout
  • Client App SDKs
    • Javascript SDK Reference
    • iOS SDK Reference
    • Android SDK Reference
    • Flutter SDK Reference
    • Xamarin SDK Reference
  • Deploy on your Cloud
    • Running locally with Docker
    • Deploy with Helm chart
    • Authenticating HTTP request with Nginx
    • Configurations
      • Environment Variables
      • authgear.yaml
      • authgear.secrets.yaml
    • Reference Architecture Diagrams
      • Google Cloud Reference Architecture
      • Azure Reference Architecture
      • AWS Reference Architecture
      • Throughput Scaling Reference
Powered by GitBook
On this page
  • 1. Queries
  • 1.1. auditLogs
  • 1.2. users
  • 1.3. node
  • 1.4. nodes
  • 1.5 groups
  • 1.6 roles
  • 1.7 getUser and getUsers Queries
  • 2. Mutations
  • 2.1. anonymizeUser
  • 2.2. createIdentity
  • 2.3. createUser
  • 2.4. deleteAuthenticator
  • 2.5. deleteAuthorization
  • 2.6. deleteIdentity
  • 2.7. deleteUser
  • 2.8. generateOOBOTPCode
  • 2.9. resetPassword
  • 2.10. revokeAllSessions
  • 2.11. revokeSession
  • 2.12. scheduleAccountAnonymization
  • 2.13. scheduleAccountDeletion
  • 2.14. sendResetPasswordMessage
  • 2.15. setDisabledStatus
  • 2.16. setVerifiedStatus
  • 2.17. unscheduleAccountAnonymization
  • 2.18. unscheduleAccountDeletion
  • 2.19. updateIdentity
  • 2.20. updateUser
  • 2.21 createGroup
  • 2.22 createRole
  • 2.23 addRoleToGroups
  • 2.24 addGroupToRoles
  • 2.25 addUserToRoles
  • 2.26 addRoleToUsers
  • 2.27 addUserToGroups
  • 2.28 addGroupToUsers
  • 2.29 updateRole
  • 2.30 updateGroup
  • 2.31 removeUserFromGroups
  • 2.32 removeRoleFromGroups
  • 2.33 removeUserFromRoles
  • 2.34 removeGroupFromRoles
  • 2.35 removeRoleFromUsers
  • 2.36 removeGroupFromUsers
  • 2.37 deleteGroup
  • 2.38 deleteRole

Was this helpful?

Edit on GitHub
  1. Reference
  2. APIs
  3. Admin API

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 > 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.

Schema:

auditLogs(
first: Int
last: Int
userIDs: [ID!]
sortDirection: SortDirection
before: String
after: String
rangeFrom: DateTime
rangeTo: DateTime
activityTypes: [AuditLogActivityType!]
): AuditLogConnection

Example:

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.

The users query depends on a search index. Hence, the data it returns is NOT immediately consistent as it requires reindexing before the most recent data and updates are included. If getting real-time user data is important for your use case, consider using the node /nodes or getUser/getUsers queries instead.

Schema:

users(
first: Int
last: Int
searchKeyword: String
sortBy: UserSortBy
sortDirection: SortDirection
before: String
after: String
): UserConnection

Example:

query {
  users(first: 2) {
    edges {
      node {
        id
        standardAttributes
      }
    }
  }
}
{
  "data": {
    "users": {
      "edges": [
        {
          "node": {
            "id": "VXNlcjo4ZGM4ZDgyjjkoKA0LTRjZGEtODZiOC03OTY4MGUwYzA5OGM",
            "standardAttributes": {
              "email": "myuser@gmail.com",
              "email_verified": true,
              "family_name": "John",
              "given_name": "Doe",
              "updated_at": 1686820949
            }
          }
        },
        {
          "node": {
            "id": "VXNlcjplMzA3OTAyaxKJuILTRjMjQtOTFjMS1jMmNkNjNhNmE0YWY",
            "standardAttributes": {
              "email": "user2@gmail.com",
              "email_verified": true,
              "family_name": "Eliano",
              "given_name": "Don",
              "updated_at": 1694359032
            }
          }
        }
      ]
    }
  }
}

1.3. node

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 {
  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 {
  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"
      }
    ]
  }
}

1.5 groups

Schema:

groups(
searchKeyword: String
excludedIDs: [ID!]
after: String
first: Int
last: Int
before: String
): GroupConnection

Example:

query {
  groups(first: 10) {
    edges {
      cursor
      node {
        id
        key
        description
      }
    }
  }
}
{
  "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

Schema:

roles(
excludedIDs: [ID!]
last: Int
before: String
after: String
first: Int
searchKeyword: String
): RoleConnection

Example:

query {
  roles(first: 10) {
    edges {
      cursor
      node {
        id
        key
        description
        groups {
          edges{
            node {
              key
            }
          }
        }
      }
    }
  }
}
{
  "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"
          }
        }
      ]
    }
  }
}

1.7 getUser and 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. Unlike the users() query, the result from the getUser and getUsers queries is immediately consistent.

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:

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!

Note: To use any loginID key, you must first enable the corresponding Login Method in your Authgear Portal. For example, enable Mobile login method to create an identity using phone number.

Example:

mutation {
  createIdentity(input: {userID: "<ENCODED USER ID>", definition: {loginID: {key: "email", value: "user@gmail.com"}}, password: "@x1ujD-9$"}) {
    identity {
      id
      claims
    }
  }
}
{
  "data": {
    "createIdentity": {
      "identity": {
        "claims": {
          "email": "user@gmail.com",
          "https://authgear.com/claims/login_id/key": "email",
          "https://authgear.com/claims/login_id/original_value": "user@gmail.com",
          "https://authgear.com/claims/login_id/type": "email",
          "https://authgear.com/claims/login_id/value": "user@gmail.com"
        },
        "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:

mutation {
  createUser(input: {definition: {loginID: {key: "email", value: "user@gmail.com"}}, password:"my$ecurepa55"}) {
    user{
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "createUser": {
      "user": {
        "id": "VXNlciklODRkMzdjZi1hZDQ5LTRiZDItOTMzZJ2tOGY1YThlYjc34RE",
        "standardAttributes": {
          "email": "user@gmail.com",
          "email_verified": false,
          "updated_at": 1694713743
        }
      }
    }
  }
}

2.4. deleteAuthenticator

This mutation deletes an authenticator for a specific user.

Schema:

deleteAuthenticator(input: DeleteAuthenticatorInput!): DeleteAuthenticatorPayload!

Example:

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:

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:

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:

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:

mutation {
  generateOOBOTPCode(input: {purpose: LOGIN, target: "user@gmail.com"}) {
    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 1:

mutation {
  resetPassword(input: {userID: "<ENCODED USER ID>", password: "n3w-p4$s"}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "resetPassword": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "email_verified": false,
          "updated_at": 1694742340
        }
      }
    }
  }
}

Example 2 (send new password to user):

You can include sendPassword: true and setPasswordExpired: true in the input for the resetPassword mutation to send the new password to a user and set it as expired so they can set a new one the next time they log in. Here is an example of the mutation:

mutation {
  resetPassword(input: {userID: "<ENCODED USER ID>", password: "n3w-p4$s", sendPassword: true, setPasswordExpired: true}) {
    user {
      id
      standardAttributes
    }
  }
}

2.10. revokeAllSessions

With the revokeAllSessions mutation, you can revoke all sessions for a specific user.

Schema:

revokeAllSessions(input: RevokeAllSessionsInput!): RevokeAllSessionsPayload!

Example:

mutation {
  revokeAllSessions(input: {userID: "<ENCODED USER ID>"}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "revokeAllSessions": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "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:

mutation {
  revokeSession(input: {sessionID: "<ENCODED SESSION ID>"}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "revokeSession": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "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:

mutation {
  scheduleAccountAnonymization(input: {userID: "<ENCODED USER ID>"}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "scheduleAccountAnonymization": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "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:

mutation {
  scheduleAccountDeletion(input: {userID: "<ENCODED USER ID>"}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "scheduleAccountDeletion": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "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:

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:

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:

mutation {
  setVerifiedStatus(input: {userID: "<ENCODED USER ID>", claimName: "email", claimValue: "user@gmail.com", isVerified: true}) {
    user {
      id
      verifiedClaims {
        name
        value
      }
    }
  } 
}
{
  "data": {
    "setVerifiedStatus": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "verifiedClaims": [
          {
            "name": "email",
            "value": "myapkneeds@gmail.com"
          }
        ]
      }
    }
  }
}

2.17. unscheduleAccountAnonymization

This mutation allows you to cancel a previously scheduled mutation.

Schema:

unscheduleAccountAnonymization(input: UnscheduleAccountAnonymizationInput!): UnscheduleAccountAnonymizationPayload!

Example:

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:

mutation {
  unscheduleAccountDeletion(input: {userID: "<ENCODED USER ID>"}) {
    user {
      id
    }
  } 
}
{
  "data": {
    "unscheduleAccountDeletion": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse"
      }
    }
  }
}

2.19. updateIdentity

The updateIdentity mutation updates an existing identiy of a user.

Schema:

updateIdentity(input: UpdateIdentityInput!): UpdateIdentityPayload!

Example:

mutation {
  updateIdentity(input: { definition: {loginID: {key: "email", value: "user@gmail.com"}}, userID: "<ENCODED USER ID>", identityID: "<ENCODED IDENTITY ID>"}) {
    user {
      id
    }
  } 
}
{
  "data": {
    "updateIdentity": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse"
      }
    }
  }
}

2.20. updateUser

You can use this mutation to update an existing user's details. You can update standard attributes such as email, phone, family_name, given_name, and gender for the user. Or you can modify custom fields using the customAttributes argument.

Schema:

updateUser(input: UpdateUserInput!): UpdateUserPayload!

Example 1 (Standard Attributes):

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:

{
  "standardAttributes": {
    "family_name": "John",
    "given_name": "Doe",
    "gender": "male"
  }
}
mutation ($standardAttributes: UserStandardAttributes) {
  updateUser(input: {userID: "<ENCODED USER ID>", standardAttributes: $standardAttributes}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "updateUser": {
      "user": {
        "id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
        "standardAttributes": {
          "email": "user@gmail.com",
          "email_verified": true,
          "family_name": "John",
          "gender": "male",
          "given_name": "Doe",
          "updated_at": 1694947082
        }
      }
    }
  }
}

Example 2 (Custom Attributes)

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
    }
  }
}
{
  "data": {
    "updateUser": {
      "user": {
        "customAttributes": {
          "town": "John"
        },
        "id": "VABlcjo2Y2I3KBU9Zi0zNGYwLTRhNTPdYjQ3ZS0wYWWeMWYzNzQyA1A"
      }
    }
  }
}

2.21 createGroup

Run this mutation to add a new access management group to your Authgear application.

Schema:

createGroup(input: CreateGroupInput!): CreateGroupPayload!

Example:

mutation {
  createGroup(input: {key: "test_group", name: "Test group", description: "This is a test group created using the Admin API"}) {
    group {
      id
    }
  }
}
{
  "data": {
    "createGroup": {
      "group": {
        "id": "R3JvdXA6YTUxYTNmMWQtMDE0ZC00N2JmLTgwNDQtMjEzOTczZDJlMTkx"
      }
    }
  }
}

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.

Schema:

createRole(input: CreateRoleInput!): CreateRolePayload!

Example:

mutation {
  createRole(input: {key: "test_role", name: "Test role", description: "This is a test role created using the Admin API"}) {
    role {
      id
    }
  }
}
{
  "data": {
    "createRole": {
      "role": {
        "id": "Um9sZTo2NzNhZGE3Mi1mYWI1LTRiMmMtOTBmYy1hMjY1YmQxY2Q2YjA"
      }
    }
  }
}

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.

Schema:

addRoleToGroups(input: AddRoleToGroupsInput!): AddRoleToGroupsPayload!

Example:

mutation {
  addRoleToGroups(input: {roleKey: "test_role", groupKeys: ["test_group", "another_group"]}) {
    role {
      id
    }
  }
}
{
  "data": {
    "addRoleToGroups": {
      "role": {
        "id": "Um9sZTo2NzNhZGE3Mi1mYWI1LTRiMmMtOTBmYy1hMjY1YmQxY2Q2YjA"
      }
    }
  }
}

2.24 addGroupToRoles

Adds a group to one or more roles in a single operation.

Schema:

addGroupToRoles(input: AddGroupToRolesInput!): AddGroupToRolesPayload!

Example:

mutation {
  addGroupToRoles(input: {groupKey: "test_group", roleKeys: ["test_role", "another_role"]}) {
    group {
      id
    }
  }
}
{
  "data": {
    "addGroupToRoles": {
      "group": {
        "id": "R3JvdXA6YTUxYTNmMWQtMDE0ZC00N2JmLTgwNDQtMjEzOTczZDJlMTkx"
      }
    }
  }
}

2.25 addUserToRoles

Adds a user to one or more roles in a single operation.

Schema:

addUserToRoles(input: AddUserToRolesInput!): AddUserToRolesPayload!

Example:

mutation {
  addUserToRoles(input: {userID: "<ENCODED USER ID>", roleKeys: ["test_role", "another_role"]}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "addUserToRoles": {
      "user": {
        "id": "VXNlcjomMyOS02ZGIzlmZWQxN2LTRhMTgtYWE3My03NzQxM5YzcxZmQ",
        "standardAttributes": {
          "email": "user2@example.com",
          "email_verified": false,
          "family_name": "Doe",
          "given_name": "John",
          "name": "John Doe",
          "updated_at": 1712213796
        }
      }
    }
  }
}

2.26 addRoleToUsers

Adds a role to one or more users in a single operation.

Schema:

addRoleToUsers(input: AddRoleToUsersInput!): AddRoleToUsersPayload!

Example:

mutation {
  addRoleToUsers(input: {roleKey: "test_role", userIDs: ["<ENCODED USER ID>", "<ANOTHER ENCODED USER ID>"]}) {
    role {
      id
    }
  }
}
{
  "data": {
    "addRoleToUsers": {
      "role": {
        "id": "Um9sZTo2NzNhZGE3Mi1mYWI1LTRiMmMtOTBmYy1hMjY1YmQxY2Q2YjA"
      }
    }
  }
}

2.27 addUserToGroups

Adds a user to one or more groups in a single operation.

Schema:

addUserToGroups(input: AddUserToGroupsInput!): AddUserToGroupsPayload!

Example:

mutation {
  addUserToGroups(input: {userID: "<ENCODED USER ID>", groupKeys: ["test_group", "another_group"]}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "addUserToGroups": {
      "user": {
        "id": "VXNlcjo5YzcxZmMyOS02ZGI2LTRhMTgtYWE3My03NzQxMzlmZWQxNmQ",
        "standardAttributes": {
          "email": "user2@example.com",
          "email_verified": false,
          "family_name": "Doe",
          "given_name": "John",
          "name": "John Doe",
          "updated_at": 1712213796
        }
      }
    }
  }
}

2.28 addGroupToUsers

Adds a group to one or more user in a single operation.

Schema:

addGroupToUsers(input: AddGroupToUsersInput!): AddGroupToUsersPayload!

Example:

mutation {
  addGroupToUsers(input: {groupKey: "test_group", userIDs: ["<ENCODED USER ID>", "<ANOTHER ENCODED USER ID>"]}) {
    group {
      id
    }
  }
}
{
  "data": {
    "addGroupToUsers": {
      "group": {
        "id": "R3JvdXA6YTUxYTNmMWQtMDE0ZC00N2JmLTgwNDQtMjEzOTczZDJlMTkx"
      }
    }
  }
}

2.29 updateRole

Updates details about an existing role.

Schema:

updateRole(input: UpdateRoleInput!): UpdateRolePayload!

Example:

mutation {
  updateRole(input: {id:"<ENCODED ROLE ID>", key: "test_role_updated", name: "Test Role Updated", description: "Updated version of this role"}) {
    role {
      id
    }
  }
}
{
  "data": {
    "updateRole": {
      "role": {
        "id": "Um9sZTo2ODk1YWVhZi0yM2U4LTQ5ODYtYWQ3NC1mY2VlZWEwNWQwMzU"
      }
    }
  }
}

Note: Pass null as the value of key, name or description if you do not wish to update them and pass and empty string ("") to delete the value of name and description. Also, some GrahpQL libraries may not allow you to pass a literal null directly in the query, in such cases, use a variable to defind the value of input.

2.30 updateGroup

Updates details about an existing group.

Schema:

updateGroup(input: UpdateGroupInput!): UpdateGroupPayload!

Example:

mutation {
  updateGroup(input: {id:"<ENCODED GROUP ID>", key: "test_group_updated", name: "Test Group Updated", description: "Updated version of this group"}) {
    group {
      id
    }
  }
}
{
  "data": {
    "updateGroup": {
      "group": {
        "id": "R3JvdXA6NzI3MTMxNDgtMzIzMy00ZWVjLTlhOGMtYWNiYjg2MWY5OTlk"
      }
    }
  }
}

Note: Pass null as the value of key, name or description if you do not wish to update them and pass and empty string ("") to delete the value of name and description. Also, some GrahpQL libraries may not allow you to pass a literal null directly in the query, in such cases, use a variable to defind the value of input.

2.31 removeUserFromGroups

Removes a user from one or more groups they're currently in.

Schema:

removeUserFromGroups(input: RemoveUserFromGroupsInput!): RemoveUserFromGroupsPayload!

Example:

mutation {
  removeUserFromGroups(input: {userID: "<ENCODED USER ID>", groupKeys: ["test_group", "another_group"]}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "removeUserFromGroups": {
      "user": {
        "id": "VXNlcjo5YzcxZmMyOS02ZGI2LTRhMTgtYWE3My03NzQxMzlmZWQxNmQ",
        "standardAttributes": {
          "email": "user2@example.com",
          "email_verified": false,
          "family_name": "Doe",
          "given_name": "John",
          "name": "John Doe",
          "updated_at": 1712213796
        }
      }
    }
  }
}

2.32 removeRoleFromGroups

Removes a role from one or more groups.

Schema:

removeRoleFromGroups(input: RemoveRoleFromGroupsInput!): RemoveRoleFromGroupsPayload!

Example:

mutation {
  removeRoleFromGroups(input: {roleKey: "test_role", groupKeys: ["test_group", "another_role"]}) {
    role {
      id
    }
  }
}
{
  "data": {
    "removeRoleFromGroups": {
      "role": {
        "id": "Um9sZToyOWIwMDM3Yy01ZDEyLTQ3ZjQtYWVhOS1mMGRjMGJiYjk2ZTA",
      }
    }
  }
}

2.33 removeUserFromRoles

Removes a user from one or more roles.

Schema:

removeUserFromRoles(input: RemoveUserFromRolesInput!): RemoveUserFromRolesPayload!

Example:

mutation {
  removeUserFromRoles(input: {userID: "<ENCODED USER ID>", roleKeys: ["test_role", "another_role"]}) {
    user {
      id
      standardAttributes
    }
  }
}
{
  "data": {
    "removeUserFromRoles": {
      "user": {
        "id": "VXNlcjo5YzcxZmMyOS02ZGI2LTRhMTgtYWE3My03NzQxMzlmZWQxNmQ",
        "standardAttributes": {
          "email": "user2@example.com",
          "email_verified": false,
          "family_name": "Doe",
          "given_name": "John",
          "name": "John Doe",
          "updated_at": 1712213796
        }
      }
    }
  }
}

2.34 removeGroupFromRoles

Removes a group from one or more roles in a single operation.

Schema:

removeGroupFromRoles(input: RemoveGroupFromRolesInput!): RemoveGroupFromRolesPayload!

Example:

mutation {
  removeGroupFromRoles(input: {groupKey: "test_group", roleKeys: ["test_role", "another_role"]}) {
    group {
      id
    }
  }
}
{
  "data": {
    "removeGroupFromRoles": {
      "group": {
        "id": "R3JvdXA6OTU4YTA2ODItMDU3ZS00ZmJjLTg3MzItNGRhMDliNWQxNTAx",
      }
    }
  }
}

2.35 removeRoleFromUsers

Removes a role from one or more users in a single operation.

Schema:

removeRoleFromUsers(input: RemoveRoleFromUsersInput!): RemoveRoleFromUsersPayload!

Example:

mutation {
  removeRoleFromUsers(input: {roleKey: "test_role", userIDs: ["<ENCODED USER ID>", "<ANOTHER ENCODED USER ID>"]}) {
    role {
      id
    }
  }
}
{
  "data": {
    "removeRoleFromUsers": {
      "role": {
        "id": "Um9sZTozMjc5NWRiNi1hOWVkLTRhOTgtOTE2MC0zMzZkZGNlOWFkMTM",
      }
    }
  }
}

2.36 removeGroupFromUsers

Removes group from one or more users in a single operation.

Schema:

removeGroupFromUsers(input: RemoveGroupFromUsersInput!): RemoveGroupToUsersPayload!

Example:

mutation {
  removeGroupFromUsers(input: {groupKey: "test_group", userIDs: ["<ENCODED USER ID>", "<ANOTHER ENCODED USER ID>"]}) {
    group {
      id
    }
  }
}
{
  "data": {
    "removeGroupFromUsers": {
      "group": {
        "id": "R3JvdXA6OTU4YTA2ODItMDU3ZS00ZmJjLTg3MzItNGRhMDliNWQxNTAx",
      }
    }
  }
}

2.37 deleteGroup

Use this mutation to delete an existing group.

Schema:

deleteGroup(input: DeleteGroupInput!): DeleteGroupPayload!

Example:

mutation {
  deleteGroup(input: {id: "<ENCODED GROUP ID>"}) {
    ok
  }
}
{
  "data": {
    "deleteGroup": {
      "ok": true
    }
  }
}

2.38 deleteRole

Use this mutation to delete an existing role.

Schema:

deleteRole(input: DeleteRoleInput!): DeleteRolePayload!

Example:

mutation {
  deleteRole(input: {id: "<ENCODED ROLE ID>"}) {
    ok
  }
}
{
  "data": {
    "deleteRole": {
      "ok": true
    }
  }
}

PreviousAPI SchemaNextUsing global node IDs

Last updated 2 months ago

Was this helpful?

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: .

The groups query returns a list of all in an Authgear project. It will return nothing if no group has been created yet. Groups can be a field in the roles query.

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 to learn more about roles and groups.

Learn more about all the queries in this collection .

Note: To update the email, phone or username standard attribute for a user using this mutation, you must first add the new value to the user's Identities. See mutation and .

https://docs.authgear.com/reference/apis/admin-api/node-id
groups
Manage Users Roles and Groups
here
createIdentity
updateIdentity