All pages
Powered by GitBook
1 of 5

User Management Examples

Learn how to perform common actions from the examples

User Management

In this section of the documentation, we've provided detailed guides showing examples of common user management actions you can perform using the Admin API. Click on any of the links below to view the corresponding guide:

Search for usersUpdate user's standard attributesUpdate user's pictureGenerate OTP code

Looking for more examples? See our full Admin API GraphQL queries and mutations examples page linked below:

Admin API Examples

Search for users

Authgear Admin GraphQL API supports searching user by keywords. Keywords include email, phone number, username, SSO subject id and standard attributes.

Search users by email

You can use the user search query to search user by email and obtains the user details.

In the following example, the project wants to search the user by email and check if they haven't set up the TOTP authenticator.

You can adjust the fields in the query based on your needs. To explore more supporting fields, you can try it out via the GraphiQL tool.

The query has a maximum limit of 20, pagination parameters should be provided to obtain all the results. See detail.

The query

query {
  users(
    searchKeyword: "user@example.com"
  ) {
    edges {
      node {
        id
        createdAt
        lastLoginAt
        isAnonymous
        isDisabled
        disableReason
        isDeactivated
        deleteAt
        standardAttributes
        loginIDs {
          id
          claims
        }
        secondaryTOTPAuthenticators {
          id
          claims
        }
      }
    }
    totalCount
  }
}

The sample response

{
  "data": {
    "users": {
      "edges": [
        {
          "node": {
            "id": "VXNlcjphZTNjMGFiZS02YjdkLTQ1ZjktOWIzZS1jMDUwYjVmY2Q3NjI",
            "lastLoginAt": "2006-01-02T03:04:05.123456Z",
            "createdAt": "2006-01-02T03:04:05.123456Z",
            "deleteAt": null,
            "isDisabled": false,
            "disableReason": null,
            "isAnonymous": false,
            "isDeactivated": false,
            "standardAttributes": {
              "email": "user@example.com",
              "email_verified": true,
              "name": "user01",
              "updated_at": 1136171045
            },
            "loginIDs": [
              {
                "claims": {
                  "email": "user@example.com",
                  "https://authgear.com/claims/login_id/key": "email",
                  "https://authgear.com/claims/login_id/original_value": "user@example.com",
                  "https://authgear.com/claims/login_id/type": "email",
                  "https://authgear.com/claims/login_id/value": "user@example.com"
                },
                "id": "SWRlbnRpdHk6NDNhMzZhMTEtM2VkNS00YjczLWE0ZjktMjQ1MWYyMzM5MmVj"
              }
            ],
            "secondaryTOTPAuthenticators": [
              {
                "claims": {
                  "https://authgear.com/claims/totp/display_name": "TOTP @ 2006-01-02T03:04:05Z"
                },
                "id": "QXV0aGVudGljYXRvcjo3NGY0NWUzNi0xMGEyLTQ0MjctYjMxYS0yY2Q3NjBjZDU4MTc"
              }
            ]
          }
        }
      ],
      "totalCount": 1
    }
  }
}

Pagination

The query

query {
  users(
    first: 5
    after: "b2Zmc2V0OjQ"
    searchKeyword: ""
    sortBy: CREATED_AT
    sortDirection: DESC
  ) {
    edges {
      node {
        id
      }
      cursor
    }
    totalCount
  }
}

The sample response

{
  "data": {
    "users": {
      "edges": [
        {
          "cursor": "b2Zmc2V0OjU",
          "node": {
            "id": "VXNlcjo2YTExYjkxNy0yNTg0LTRmNWEtOTkyMS0xN2E3ZmMzMWZjZWU"
          }
        },
        {
          "cursor": "b2Zmc2V0OjY",
          "node": {
            "id": "VXNlcjo0ZTFhZjZmYy0zM2VjLTQ5NjAtOGI2ZC00YTc5YjkxM2Q5N2Y"
          }
        },
        {
          "cursor": "b2Zmc2V0Ojc",
          "node": {
            "id": "VXNlcjphZDJjZWY5Ny0xYzk2LTQ4N2ItOWQzZS01NGVjMzJhYzUxYjY"
          }
        },
        {
          "cursor": "b2Zmc2V0Ojg",
          "node": {
            "id": "VXNlcjphMWIzMzVhMC1jYTdiLTRjMTItYmVmNC04NmNiZTQ4OGMxNzI"
          }
        },
        {
          "cursor": "b2Zmc2V0Ojk",
          "node": {
            "id": "VXNlcjphOWU2YTYwYy0wYTQ1LTQxMzctYTM3MC0wNWM1MjBlZWFkZmU"
          }
        }
      ],
      "totalCount": 30
    }
  }
}

Parameters

  • searchKeyword: Search for users by specified keyword.

  • first: The number of items to be returned. Maximum is 20.

  • after: A cursor for use in pagination. You can pass the cursor value of the last edges item to a subsequent call to fetch the next page of results.

  • sortBy: The field in which to order users. Supported values: CREATED_AT or LAST_LOGIN_AT.

  • sortDirection: The direction in which to order users by the specified field. Supported values: ASC or DESC.

Update user's standard attributes

Overview

To update the user's standard attributes:

  1. Fetch the user's original standard attributes by query first.

  2. Change the attributes payload and update the user's standard attributes by mutation.

API Details

Generate the user node id

Follow the document here to generate the user node id.

Fetch the user's standard attributes by query

The query:

query {
  node(id: "<BASE64URL_ENCODED_USER_NODE_ID>") {
    ... on User {
      standardAttributes
    }
  }
}

The sample response:

{
  "data": {
    "node": {
      "standardAttributes": {
        "name": "Name",
        "given_name": "Given Name",
        "family_name": "Family Name",
        "middle_name": "Middle Name",
        "nickname": "Nickname",
        "profile": "https://<PROFILE_URL>",
        "picture": "https://<PICTURE_URL>",
        "website": "https://<WEBSITE_URL>",
        "gender": "male",
        "birthdate": "2020-01-01",
        "zoneinfo": "Europe/London",
        "locale": "en",
        "address": {
          "country": "GB",
          "locality": "locality",
          "postal_code": "postal code",
          "region": "region",
          "street_address": "full street address"
        },
        "updated_at": 1649428136
      }
    }
  }
}

Update the user's standard attributes by mutation

Make sure to copy the original standard attributes as any attributes that are missing in the payload will be deleted. Next, change the values for attributes that you want to update.

The query:

mutation ($userID: ID!, $standardAttributes: UserStandardAttributes!) {
  updateUser(input: {userID: $userID, standardAttributes: $standardAttributes}) {
    user {
      id
      standardAttributes
      updatedAt
    }
  }
}

The variables:

{
  "userID": "<BASE64URL_ENCODED_USER_NODE_ID>",
  "standardAttributes": {
    /* Include all the original standard attributes from the previous response */
    /* and change the attributes that you want to update */
    /* The attributes that are missing in the payload will be deleted */
  }
}

The sample variables:

{
  "userID": "<BASE64URL_ENCODED_USER_NODE_ID>",
  "standardAttributes": {
    "name": "Name",
    "given_name": "Given Name",
    "family_name": "Family Name",
    "middle_name": "Middle Name",
    "nickname": "Nickname",
    "profile": "https://<PROFILE_URL>",
    "picture": "https://<PICTURE_URL>",
    "website": "https://<WEBSITE_URL>",
    "gender": "male",
    "birthdate": "2020-01-01",
    "zoneinfo": "Europe/London",
    "locale": "en",
    "address": {
      "country": "GB",
      "locality": "locality",
      "postal_code": "postal code",
      "region": "region",
      "street_address": "full street address"
    }
  }
}

The sample response:

{
  "data": {
    "updateUser": {
      "user": {
        "id": "VXNlcjo5N2IxYzkyOS04NDJjLTQxNWMtYTdkZi02OTY3ZWZkZGExNjA",
        "standardAttributes": {
          "name": "Name",
          "given_name": "Given Name",
          "family_name": "Family Name",
          "middle_name": "Middle Name",
          "nickname": "Nickname",
          "profile": "https://<PROFILE_URL>",
          "picture": "https://<PICTURE_URL>",
          "website": "https://<WEBSITE_URL>",
          "gender": "male",
          "birthdate": "2020-01-01",
          "zoneinfo": "Europe/London",
          "locale": "en",
          "address": {
            "country": "GB",
            "locality": "locality",
            "postal_code": "postal code",
            "region": "region",
            "street_address": "full street address"
          },
          "updated_at": 1649428136
        },
        "updatedAt": "2022-04-08T14:40:16.410087Z"
      }
    }
  }
}

Updating Custom Attributes

To learn how to update a user's custom attributes, see the update custom attribute example.

Update user's picture

Authgear allows your server to update the user's picture via the Admin APIs.

Overview

To update the user's picture:

  1. Make a GET request to /_api/admin/images/upload to obtain the pre-signed upload url.

  2. Make a POST request to the pre-signed upload url to upload the image file. This call returns the result url once the upload is finished.

  3. Call the Admin GraphQL API /_api/admin/graphql to update the user's standard attributes. Update the picture attribute with the result url returned by the previous call.

API Details

Obtain the per-signed upload url

Make a GET request to /_api/admin/images/upload to obtain the pre-signed upload url.

The call will look like this:

GET /_api/admin/images/upload HTTP/1.1
Host: <YOUR_APP>.authgear.cloud
Authorization: Bearer <JWT>

The call returns the pre-signed upload url:

{
  "result": {
    "upload_url": "<PRESIGNED_UPLOAD_URL>"
  }
}

Upload the picture

Upload the picture to the pre-signed upload url. We recommend you to pre-process the image before uploading. The image should be cropped into square and should be less than 10 MB.

Upload the file with FormData and the field name is file. You can construct the multipart/form-data request by most HTTP libraries.

The call will look like this:

POST <PRESIGNED_UPLOAD_URL_PATH> HTTP/1.1
Host: <YOUR_APP>.authgear.cloud
Content-Length: <CONTENT_LENGTH>
Content-Type: multipart/form-data; boundary=----boundary

----boundary
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png

<CONTENT_OF_IMAGE_FILE>
----boundary

The call returns the result url once the upload completed, the url is in format of authgearimages:///APP_ID/OBJECT_ID:

{
  "result": {
    "url": "authgearimages:///..."
  }
}

Update user's picture in the standard attributes

Follow the doc of Update user's standard attributes to update the user's picture attribute. Replace the attribute with the new picture url (e.g. authgearimages:///...) obtained by the previous upload.

Generate OTP code

Authgear Admin GraphQL API supports generating OTP code on behalf of end-user when they asks for support.

API Details

The query:

mutation ($target: String!) {
  generateOOBOTPCode(input: { target: $target }) {
    code
  }
}

The variables:

{
  "target": "<USER_EMAIL_OR_PHONE_NUMBER>"
}

The sample variables:

{
  "target": "user@example.com"
}

The sample response:

{
  "data": {
    "generateOOBOTPCode": {
      "code": "123456"
    }
  }
}