👨‍👩‍👧‍👦 Users

The users are the main entities of the identity service. We will describe the user-related concepts and details in the following.

Profile

Each user has a profile containing all user information.

It consists of the following types of data:

• Social identities: stores the user info retrieved from social sign-in (i.e., sign-in with a social connector), such as Facebook, GitHub, and WeChat.
• Custom data: stores additional user info not listed in the pre-defined user properties, such as user-preferred color and language.
• Basic data: is the basic info from the user profile. It stores all other user's properties except for identities and custom_data, such as user id, username, email, phone number, and when the user last signed in.

Here is a sample of a user's data which is retrieved from a sign-in to Facebook:

{
  "id": "iHXPuSb9eMzt",
  "username": null,
  "primaryEmail": null,
  "primaryPhone": null,
  "name": "John Joe",
  "avatar": "https://example.com/avatar.png",
  "customData": {
    "preferences": {
      "language": "en",
      "color": "#f236c9"
    }
  },
  "identities": {
    "facebook": {
      "userId": "106077000000000",
      "details": {
        "id": "106077000000000",
        "name": "John Joe",
        "email": "[email protected]",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

You can query the user profile using Admin Console or Management API, such as GET /api/users/:userId.

Basic data

Let's walk through all properties in of user's basic data.

id

id is a unique auto-generated key to identify the user in Logto.

username

username is used for sign-in with username and password.

Its value is from the username that the user first registered with. It may be null. Its non-null value should be no longer than 128 characters, only contain letters, numbers, and underscores (_), and NOT start with a number.

primary_email

primary_email is the user's email address, used for sign-in with the email and passcode.

Its value is usually from the email address that the user first registered with. It may be null. Its max length is 128.

primary_phone

primary_phone is the user's phone number, used for sign-in with the phone number and passcode from SMS.

Its value is usually from the phone number that the user first registered with. It may be null. Its non-null value should contain numbers prefixed with the country calling code (excluding the plus sign +).

name

name is the user's full name. Its max length is 128.

avatar

avatar is the URL pointing to the user's avatar image. Its max length is 2048.

If the user registers with a social connector like Google and Facebook, its value may be retrieved from the social user info.

note

This property is mapped to the picture claim in the OpenID Connect standard.

profile

profile stores additional OpenID Connect standard claims that are not included in user's properties.

Its type definition can be found at this file. Here's a copy of the type definition:

type UserProfile = Partial<{
  familyName: string;
  givenName: string;
  middleName: string;
  nickname: string;
  preferredUsername: string;
  profile: string;
  website: string;
  gender: string;
  birthdate: string;
  zoneinfo: string;
  locale: string;
  address: Partial<{
    formatted: string;
    streetAddress: string;
    locality: string;
    region: string;
    postalCode: string;
    country: string;
  }>;
}>;

note

Partial means that all properties are optional.

A difference compared to the other standard claims is that the properties in profile will only be included in the ID token or userinfo endpoint response when their values are not empty, while other standard claims will return null if the values are empty.

application_id

The value of application_id is from the application the user first signed in to. It may be null.

last_signed_in_at

last_signed_in_at is the timestamp with the timezone when the user signed in last time.

password_encrypted

password_encrypted is used to store the user's encrypted password.

Its value is from the password that the user first registered with. It may be null. If its value is non-null, its original content before encryption should be at least six characters.

password_encryption_method

password_encryption_method is used to encrypt the user's password. Its value is initialized when the user registers with the username and password. It may be null.

Logto uses Argon2's implementation node-argon2 as the encryption method by default; see the reference for details if you're interested.

Sample a password_encrypted and password_encryption_method from a user whose password is 123456:

{
  "password_encryption_method": "Argon2i",
  "password_encrypted": "$argon2i$v=19$m=4096,t=10,p=1$aZzrqpSX45DOo+9uEW6XVw$O4MdirF0mtuWWWz68eyNAt2u1FzzV3m3g00oIxmEr0U"
}

is_suspended

is_suspended is a boolean value that indicates whether a user is suspended or not. The value can be managed by calling the Logto Management API or using Admin Console.

Once a user is suspended the pre-granted refresh tokens will be revoked immediately and the user won't be able to get authenticated by Logto anymore.

Property reference

The following properties (except password_encrypted and password_encryption_method) are visible on the user profile, which means you can query them using Management API.

Name	Type	Description	Unique	Required
id	string	Unique identifier	✅	✅
username	string	Username for sign-in	✅	❌
primary_email	string	Primary email	✅	❌
primary_phone	string	Primary phone number	✅	❌
name	string	Full name	❌	❌
avatar	string	URL pointing to user's avatar image	❌	❌
identities	object	User info retrieved from social sign-in	❌	✅
custom_data	object	Additional info in customizable properties	❌	✅
application_id	string	Application ID that the user first registered	❌	✅
last_sign_in_at	date time	Timestamp when the user signed in last time	❌	✅
password_encrypted	string	Encrypted password	❌	❌
password_encryption_method	string	Password encryption method	❌	❌
is_suspended	bool	User suspend mark	❌	✅

note

• Unique: Ensures the uniqueness of the values entered into a property of a database table.
• Required: Ensures that the values entered a property of a database table can NOT be NULL.