User APIs

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Parameters

userId [UUID] Optional defaults to secure random UUID

The Id to use for the new User. If not specified a secure random UUID will be generated.

You must specify either the email or the username or both for the User. Either of these values may be used to uniquely identify the User and may be used to authenticate the User. These fields are marked as optional below, but you must specify at least one of them.

Request Body

sendSetPasswordEmail [Boolean] Optional defaults to false

Indicates to FusionAuth to send the User an email asking them to set their password. The Email Template that is used is configured in the System Configuration setting for Set Password Email Template.

If you set this value to true the password field is then ignored, FusionAuth will set the initial password to a securely generated random string.

If you have also enabled email verification and do not select to skip verification using the skipVerification parameter, only the setup password email will be sent to the user. Setting up the password using the email sent during this user create operation will implicitly verify the User’s email if it is not already verified.

If the SMTP email configuration is not complete, or disabled, this value is ignored.

skipVerification [Boolean] Optional defaults to false

Indicates to FusionAuth that it should skip email verification even if it is enabled. This is useful for creating admin or internal User accounts.

user.birthDate [String] Optional

An ISO-8601 formatted date of the User’s birthdate such as YYYY-MM-DD.

user.data [Object] Optional

An object that can hold any information about a User that should be persisted.

user.email [String] Optional

The User’s email address. An email address is a unique in FusionAuth and stored in lower case.

If email is not provided, then the username will be required.

user.encryptionScheme [String] Optional defaults to salted-pbkdf2-hmac-sha256

The method for encrypting the User’s password. The following encryptors are provided with FusionAuth:

• salted-md5

• salted-sha256

• salted-hmac-sha256

• salted-pbkdf2-hmac-sha256

• bcrypt

You can also create your own password encryptor. See the Password Encryptors section for more information.

user.expiry [Long] Optional

The expiration instant of the User’s account. An expired user is not permitted to login.

user.factor [String] Optional

The factor used by the password encryption scheme. If not provided, the PasswordEncryptor provides a default value. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

user.firstName [String] Optional

The first name of the User.

user.fullName [String] Optional

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.imageUrl [String] Optional

The URL that points to an image file that is the User’s profile image.

user.lastName [String] Optional

The User’s last name.

user.middleName [String] Optional

The User’s middle name.

user.mobilePhone [String] Optional

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Optional Available since 1.7.0

The email address of the user’s parent or guardian. This field is used to allow a child user to identify their parent so FusionAuth can make a request to the parent to confirm the parent relationship.

Family configuration must be enabled in the tenant Family configuration and the corresponding family email templates must be configured for FusionAuth to notify the parent during user creation.

user.password [String] Optional

The User’s plain texts password. This password will be hashed and the provided value will never be stored and cannot be retrieved.

This field is optional only if sendSetPasswordEmail is set to true. By default sendSetPasswordEmail is false, and then this field will be required.

user.passwordChangeRequired [Boolean] Optional defaults to false

Indicates that the User’s password needs to be changed during their next login attempt.

user.preferredLanguages [Array<String>] Optional

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.timezone [String] Optional

The User’s preferred timezone. The string must be in an IANA time zone format. For example:

America/Denver or US/Mountain

users.twoFactorDelivery [String] Optional defaults to None

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

When using TextMessage the User will also need a valid mobilePhone.

user.twoFactorEnabled [Boolean] Optional defaults to false

Determines if the User has two factor authentication enabled for their account or not.

+ See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API.

user.twoFactorSecret [String] Optional

The Base64 encoded secret used to generate Two Factor verification codes.

You may optionally use value provided in the secret field returned by the Two Factor Secret API instead of generating this value yourself.

Unless you are using TextMessage as your delivery type, ensure you are able to share the secret with the User before enabling Two Factor authentication. Beginning in version 1.17.0, if you do create a User with TextMessage set as the twoFactorDelivery type and you omit this value, the secret will be generated for you. The secret can be generated because it is not necessary to share the secret with the User for this delivery method.

When using None as the twoFactorDelivery this value will be required.

user.username [String] Optional

The username of the User. The username is stored and returned as a case sensitive value, however a username is considered unique regardless of the case. bob is considered equal to BoB so either version of this username can be used whenever providing it as input to an API.

If username is not provided, then the email will be required.

user.usernameStatus [String] Optional

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

This state is managed by CleanSpeak, it may be changed by setting it on this request.

{
  "user": {
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "encryptionScheme": "salted-sha256",
    "factor": 24000,
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123"
  }
}

Response Body

token [String] Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

user.active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

user.birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

user.connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data [Object]

An object that can hold any information about the User that should be persisted.

user.email [String]

The User’s email address.

user.expiry [Long]

The expiration instant of the User’s account. An expired user is not permitted to login.

user.firstName [String]

The first name of the User.

user.fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

The URL that points to an image file that is the User’s profile image.

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Available since 1.7.0

The email address of the user’s parent or guardian. If this value was provided during a create or update operation, this value value will only remain until the child is claimed by a parent.

user.passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens [Map<String,String>] Available since 1.1.0

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

user.tenantId [UUID]

The Id of the Tenant that this User belongs to.

user.timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

user.twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

user.twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

user.username [String]

The username of the User.

user.usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified [Boolean]

Whether or not the User’s email has been verified.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxVU5ON0pIUVc4X21ROHBTaWZKbzBXekdybDlTbTRnIn0.eyJleHAiOjE1ODY4ODQzNzksImlhdCI6MTU4Njg4NDMxOSwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlVTRVJfQ1JFQVRFIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.Z1jV8xDcayZZDBdLRVd2fIyowhstRI4Dgk7_u2XFerc",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "memberships": [{
      "data": {
        "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
      },
      "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5",
      "id": "27218714-305e-4408-bac0-23e7e1ddceb6",
      "insertInstant": 1471786482322
    }],
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "timezone": "America/Chicago",
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Request Parameters

userId [UUID] Required

The unique Id of the User to retrieve.

Request Parameters

loginId [String] Required

The unique Id of the User to retrieve. The loginId can be either the email or username.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Retrieve a User by email

Request Parameters

email [String] Required

The email of the User to retrieve.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Retrieve a User by username

Request Parameters

username [String] Required

The username of the User to retrieve.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Retrieve a User by Change Password Id

Request Parameters

changePasswordId [String] Required

The change password Id associated with the user when the Forgot Password workflow has been started.

Request Parameters

verificationId [String] Required

The verification Id associated with the user when the Email verification process has been started.

Response Body

token [String] Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

user.active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

user.birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

user.connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data [Object]

An object that can hold any information about the User that should be persisted.

user.email [String]

The User’s email address.

user.encryptionScheme [String] Available since 1.20.1

The encryption scheme used to hash the password for this user. This value is only returned when the user is retrieved using an API key.

user.expiry [Long]

The expiration instant of the User’s account. An expired user is not permitted to login.

user.firstName [String]

The first name of the User.

user.fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

The URL that points to an image file that is the User’s profile image.

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.memberships [Array]

The list of memberships for the User.

user.memberships[x].data [Object]

An object that can hold any information about the User for this membership that should be persisted.

user.memberships[x].groupId [UUID]

The Id of the Group of this membership.

user.memberships[x].id [UUID]

The unique Id of this membership.

user.memberships[x].insertInstant [Long]

The instant that the membership was created.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Available since 1.7.0

The email address of the user’s parent or guardian. If this value was provided during a create or update operation, this value value will only remain until the child is claimed by a parent.

user.passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens [Map<String,String>] Available since 1.1.0

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

user.tenantId [UUID]

The Id of the Tenant that this User belongs to.

user.timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

user.twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

user.twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

user.username [String]

The username of the User.

user.usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified [Boolean]

Whether or not the User’s email has been verified.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxVU5ON0pIUVc4X21ROHBTaWZKbzBXekdybDlTbTRnIn0.eyJleHAiOjE1ODY4ODQzNzksImlhdCI6MTU4Njg4NDMxOSwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlVTRVJfQ1JFQVRFIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.Z1jV8xDcayZZDBdLRVd2fIyowhstRI4Dgk7_u2XFerc",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "memberships": [{
      "data": {
        "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
      },
      "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5",
      "id": "27218714-305e-4408-bac0-23e7e1ddceb6",
      "insertInstant": 1471786482322
    }],
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "timezone": "America/Chicago",
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Request Parameters

userId [UUID] Required

The Id of the User to update.

Request Body

skipVerification [Boolean] Optional defaults to false

Indicates to FusionAuth that it should skip email verification even if it is enabled. This is useful for creating admin or internal User accounts.

user.birthDate [String] Optional

An ISO-8601 formatted date of the User’s birthdate such as YYYY-MM-DD.

user.data [Object] Optional

An object that can hold any information about a User that should be persisted.

user.email [String] Optional

The User’s email address. An email address is a unique in FusionAuth and stored in lower case.

If email is not provided, then the username will be required.

user.encryptionScheme [String] Optional defaults to salted-pbkdf2-hmac-sha256

The method for encrypting the User’s password. The following encryptors are provided with FusionAuth:

• salted-md5

• salted-sha256

• salted-hmac-sha256

• salted-pbkdf2-hmac-sha256

• bcrypt

This field is ignored unless the password field is also provided. If omitted and the password is specified, the default encryption scheme will be used.

You can also create your own password encryptor. See the Password Encryptors section for more information.

user.expiry [Long] Optional

The expiration instant of the User’s account. An expired user is not permitted to login.

user.factor [String] Optional

The factor used by the password encryption scheme. If not provided, the PasswordEncryptor provides a default value. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

This field is ignored unless the password field is also provided. If omitted and the password is specified, the default factor for the encryption scheme will be used.

user.firstName [String] Optional

The first name of the User.

user.fullName [String] Optional

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.imageUrl [String] Optional

The URL that points to an image file that is the User’s profile image.

user.lastName [String] Optional

The User’s last name.

user.middleName [String] Optional

The User’s middle name.

user.mobilePhone [String] Optional

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Optional Available since 1.7.0

The email address of the user’s parent or guardian. This field is used to allow a child user to identify their parent so FusionAuth can make a request to the parent to confirm the parent relationship.

Family configuration must be enabled in the tenant Family configuration and the corresponding family email templates must be configured for FusionAuth to notify the parent during user creation.

user.password [String] Optional

The User’s plain texts password. This password will be hashed and the provided value will never be stored and cannot be retrieved.

+ If this parameter is provided it indicates you wish to change the User’s password. If you do not want to change the User’s password omit this field from the request.

user.passwordChangeRequired [Boolean] Optional defaults to false

Indicates that the User’s password needs to be changed during their next login attempt.

user.preferredLanguages [Array<String>] Optional

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.timezone [String] Optional

The User’s preferred timezone. The string must be in an IANA time zone format. For example:

America/Denver or US/Mountain

users.twoFactorDelivery [String] Optional defaults to None

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

When using TextMessage the User will also need a valid mobilePhone.

If Two Factor authentication is already enabled for this user, the delivery may not be modified. In order to change the delivery type you must first disable Two Factor authentication and re-enable with a new delivery type.

user.twoFactorEnabled [Boolean] Optional defaults to false

Determines if the User has two factor authentication enabled for their account or not.

If Two Factor authentication is already enabled for this user disabling Two Factor authentication will reset the delivery type and secret.

See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API.

user.twoFactorSecret [String] Optional

The Base64 encoded secret used to generate Two Factor verification codes.

You may optionally use value provided in the secret field returned by the Two Factor Secret API instead of generating this value yourself.

Unless you are using TextMessage as your delivery type, ensure you are able to share the secret with the User before enabling Two Factor authentication. Beginning in version 1.17.0, if you do create a User with TextMessage set as the twoFactorDelivery type and you omit this value, the secret will be generated for you. The secret can be generated because it is not necessary to share the secret with the User for this delivery method.

When using None as the twoFactorDelivery this value will be required.

If Two Factor authentication is already enabled for this user, the secret may not be modified. In order to change the secret you must first disable Two Factor authentication and re-enable with a new secret.

user.username [String] Optional

The username of the User. The username is stored and returned as a case sensitive value, however a username is considered unique regardless of the case. bob is considered equal to BoB so either version of this username can be used whenever providing it as input to an API.

If username is not provided, then the email will be required.

user.usernameStatus [String] Optional

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

This state is managed by CleanSpeak, it may be changed by setting it on this request.

{
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "encryptionScheme": "salted-sha256",
    "factor": 24000,
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123"
  }
}

Response Body

token [String] Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

user.active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

user.birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

user.connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data [Object]

An object that can hold any information about the User that should be persisted.

user.email [String]

The User’s email address.

user.expiry [Long]

The expiration instant of the User’s account. An expired user is not permitted to login.

user.firstName [String]

The first name of the User.

user.fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

The URL that points to an image file that is the User’s profile image.

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.memberships [Array]

The list of memberships for the User.

user.memberships[x].data [Object]

An object that can hold any information about the User for this membership that should be persisted.

user.memberships[x].groupId [UUID]

The Id of the Group of this membership.

user.memberships[x].id [UUID]

The unique Id of this membership.

user.memberships[x].insertInstant [Long]

The instant that the membership was created.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Available since 1.7.0

The email address of the user’s parent or guardian. If this value was provided during a create or update operation, this value value will only remain until the child is claimed by a parent.

user.passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens [Map<String,String>] Available since 1.1.0

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

user.tenantId [UUID]

The Id of the Tenant that this User belongs to.

user.timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

user.twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

user.twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

user.username [String]

The username of the User.

user.usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified [Boolean]

Whether or not the User’s email has been verified.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxVU5ON0pIUVc4X21ROHBTaWZKbzBXekdybDlTbTRnIn0.eyJleHAiOjE1ODY4ODQzNzksImlhdCI6MTU4Njg4NDMxOSwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlVTRVJfQ1JFQVRFIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.Z1jV8xDcayZZDBdLRVd2fIyowhstRI4Dgk7_u2XFerc",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "memberships": [{
      "data": {
        "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
      },
      "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5",
      "id": "27218714-305e-4408-bac0-23e7e1ddceb6",
      "insertInstant": 1471786482322
    }],
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "timezone": "America/Chicago",
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Request Parameters

userId [UUID] Required

The Id of the User to delete.

hardDelete [Boolean] Optional defaults to false

To Permanently delete a user from FusionAuth set this value to true. Once a user has been permanently deleted, the action cannot be undone. When this value is set to false the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user.

Request Parameters

dryRun [Boolean] Optional defaults to false

To preview the user Ids to be deleted by the request without applying the requested action set this value to true.

hardDelete [Boolean] Optional defaults to false

To Permanently delete a user from FusionAuth set this value to true. Once a user has been permanently deleted, the action cannot be undone. When this value is set to false the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user.

query [String] Optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

Database search engine

This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine.

queryString [String] Optional Available since 1.13.0

The Elasticsearch query string that is used to search for Users to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Database search engine

The Elasticsearch query string DSL is not supported for the database search engine. Database search limits effective queries to single search terms that may match the following fields on the User:

• firstName

• lastName

• fullName

• email

• username

The following is an example bulk delete request with a queryString value that is compatible with the database search engine:

DELETE /api/user/bulk?queryString=jared%40fusionauth.io

userId [UUID] Optional

The Id of the User to delete. Repeat this parameter for each user to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Request Body

dryRun [Boolean] Optional defaults to false

To preview the user Ids to be deleted by the request without applying the requested action set this value to true.

hardDelete [Boolean] Optional defaults to false

To Permanently delete a user from FusionAuth set this value to true. Once a user has been permanently deleted, the action cannot be undone. When this value is set to false the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user.

query [String] Optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

Database search engine

This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine.

queryString [String] Optional Available since 1.13.0

The Elasticsearch query string that is used to search for Users to be deleted. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Database search engine

The Elasticsearch query string DSL is not supported for the database search engine. Database search limits effective queries to single search terms that may match the following fields on the User:

• firstName

• lastName

• fullName

• email

• username

The following is an example bulk delete request with a queryString value that is compatible with the database search engine:

DELETE /api/user/bulk?queryString=jared%40fusionauth.io

userIds [Array] Optional

An array of User Ids to delete. The userIds, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

{
  "dryRun": true,
  "hardDelete": true,
  "userIds": [
    "5c1dc1a8-2fc8-4ae0-9372-e994be0f4341",
    "dbf59ee1-2d24-4ea0-b977-2b6e2a5350bf",
    "3e74294d-7de7-45a4-9592-4a198ddbdc73",
    "cfaf34a0-aa66-4d3a-af14-6dbc5f9fb577",
    "a2eb9268-e6f1-45f4-8eaa-50c0154983fe",
    "b1b42d6b-3b44-47fb-bb32-26e0c71c62d3",
    "8c91cb08-27df-4725-b3a8-98631bc8d9af",
    "54df878b-c0a1-4951-a63a-3cf2f97edd17",
    "946b3deb-25a5-4155-b137-bb5202d2ac98"
  ]
}

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "bool": {
              "must": [
                {
                  "match": {
                    "registrations.applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32"
                  }
                },
                {
                  "match": {
                    "registrations.verified": false
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
}

{
  "dryRun": true,
  "hardDelete": true,
  "query": "{\"bool\":{\"must\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"3c219e58-ed0e-4b18-ad48-f4f92793ae32\"}},{\"match\":{\"registrations.verified\":false}}]}}}}]}}"
}

{
  "bool" : {
    "must" : [ [ {
      "nested" : {
        "path" : "registrations",
        "query" : {
          "bool" : {
            "must" : [ {
              "match" : {
                "registrations.applicationId" : "c50329fa-93e5-4618-8d9f-73d0ab069a54"
              }
            }, {
              "match" : {
                "registrations.roles" : "admin"
              }
            } ]
          }
        }
      }
    } ] ]
  }
}

{
  "dryRun": true,
  "hardDelete": true,
  "query": "{\"bool\":{\"must\":[[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"c50329fa-93e5-4618-8d9f-73d0ab069a54\"}},{\"match\":{\"registrations.roles\":\"admin\"}}]}}}}]]}}"
}

{
  "dryRun": true,
  "hardDelete": true,
  "queryString": "email:*@fusionauth.io"
}

{
  "dryRun": true,
  "hardDelete": true,
  "queryString": "memberships.groupId:7f318a9d-3de4-4ded-9b53-1d97fd730868"
}

{
  "dryRun": true,
  "hardDelete": true,
  "queryString": "tenantId:39666465-6535-3731-3139-666363356438"
}

Response Body

dryRun [Boolean]

Whether the request was a dry run or the requested action was applied.

hardDelete [Boolean]

Whether the requested action was deactivation or permanent deletion.

total [Integer]

The count of affected Users.

userIds [Array<UUID>]

The list of affected User Ids. This field is omitted from the response when no users were affected by the request.

{
  "dryRun" : true,
  "hardDelete": true,
  "total" : 2,
  "userIds" : [ "00000000-0000-0001-0000-000000000000", "00000000-0000-0001-0000-000000000001" ]
}

Request Parameters

userId [UUID] Required

The Id of the User to reactivate.

Response Body

token [String] Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

user.active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

user.birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

user.connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data [Object]

An object that can hold any information about the User that should be persisted.

user.email [String]

The User’s email address.

user.expiry [Long]

The expiration instant of the User’s account. An expired user is not permitted to login.

user.firstName [String]

The first name of the User.

user.fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

The URL that points to an image file that is the User’s profile image.

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.memberships [Array]

The list of memberships for the User.

user.memberships[x].data [Object]

An object that can hold any information about the User for this membership that should be persisted.

user.memberships[x].groupId [UUID]

The Id of the Group of this membership.

user.memberships[x].id [UUID]

The unique Id of this membership.

user.memberships[x].insertInstant [Long]

The instant that the membership was created.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Available since 1.7.0

The email address of the user’s parent or guardian. If this value was provided during a create or update operation, this value value will only remain until the child is claimed by a parent.

user.passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens [Map<String,String>] Available since 1.1.0

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

user.tenantId [UUID]

The Id of the Tenant that this User belongs to.

user.timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

user.twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

user.twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

user.username [String]

The username of the User.

user.usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified [Boolean]

Whether or not the User’s email has been verified.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxVU5ON0pIUVc4X21ROHBTaWZKbzBXekdybDlTbTRnIn0.eyJleHAiOjE1ODY4ODQzNzksImlhdCI6MTU4Njg4NDMxOSwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlVTRVJfQ1JFQVRFIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.Z1jV8xDcayZZDBdLRVd2fIyowhstRI4Dgk7_u2XFerc",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "memberships": [{
      "data": {
        "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
      },
      "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5",
      "id": "27218714-305e-4408-bac0-23e7e1ddceb6",
      "insertInstant": 1471786482322
    }],
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "timezone": "America/Chicago",
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

You must provide either the email or the username field for each User. This will be used to authenticate the User and is also the User’s unique identifier. These fields are marked as optional below, but you must provide one of them.

Request Body

encryptionScheme [String] Optional

The encryption scheme used to encrypt plaintext passwords encountered in the request. If this value is omitted the system configured value will be used.

The following encryptors are provided with FusionAuth:

• salted-md5

• salted-sha256

• salted-hmac-sha256

• salted-pbkdf2-hmac-sha256

• bcrypt

factor [Integer] Optional

The factor used to encrypt plaintext passwords encountered in the request. If this value is omitted the system configured value will be used.

users [Array] Required

The list of Users to import.

users[x].active [Boolean] Optional defaults to false

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. Generally this should be set to true during the bulk import.

users[x].birthDate [String] Optional

YYYY-MM-DD formatted date of the User’s birth.

users[x].data [Object] Optional

An object that can hold any information about a User that should be persisted.

users[x].email [String] Optional

The User’s email address.

users[x].encryptionScheme [String] Optional defaults to salted-pbkdf2-hmac-sha256

The method for encrypting the User’s password. If the password value is already encrypted this value is required.

Omitting this value indicates the password is in plain text and it will be encrypted using the default password encryptor.

Importing users with plain text passwords is very slow because FusionAuth will hash each one using the default scheme. Grab some popcorn and catch a movie it can take up to several hundred milliseconds per user.

The following encryptors are provided with FusionAuth:

• salted-md5

• salted-sha256

• salted-hmac-sha256

• salted-pbkdf2-hmac-sha256

• bcrypt

  If you don’t see the scheme needed for importing your existing password you can also create your own password encryptor or we can build it for you. See the Password Encryptors section for more information.

users[x].expiry [Long] Optional

The expiration instant of the User’s account. After this instant is reached, the User’s account will automatically be deactivated.

users[x].factor [String] Optional

The factor used by the password encryption scheme. If omitted the factor will determined either by the system configured factor or the default value defined by the PasswordEncryptor.

The factor will generally be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

users[x].firstName [String] Optional

The first name of the User.

users[x].fullName [String] Optional

The User’s full name as a separate field that is not calculated from firstName and lastName.

users[x].id [UUID] Optional defaults to secure random UUID

The Id of the User. If not specified a secure random UUID will be generated.

users[x].imageUrl [String] Optional

The URL that points to an image file that is the User’s profile image.

users[x].insertInstant [Long] Optional defaults to now

The instant when user was created.

users[x].lastName [String] Optional

The User’s last name.

users[x].memberships [Array] Optional

The list of memberships for the User.

users[x].memberships[x].data [Object] Optional

An object that can hold any information about the User for this membership that should be persisted.

users[x].memberships[x].groupId [UUID] Required

The Id of the Group of this membership.

users[x].memberships[x].id [UUID] Optional defaults to secure random UUID

The unique Id of this membership. If not specified a secure random UUID will be generated.

users[x].middleName [String] Optional

The User’s middle name.

users[x].mobilePhone [String] Optional

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

users[x].password [String] Required

The User’s password. If encryptionScheme is provided this value is the existing password hash, if encryptionScheme is not provided this value is assumed to be plain text and it will be hashed during import.

users[x].passwordChangeRequired [Boolean] Optional defaults to false

Indicates that the User’s password needs to be changed during the next login attempt.

users[x].passwordLastUpdateInstant [Long] Optional defaults to now

Indicates that last instant the password was changed.

If encryptionScheme is omitted this value will be ignored and set to now.

Note that if you have enabled password expiration or plan to do so in the future and you set this value to 0 or some other arbitrary time in the past that is greater than the password expiration value in days, these users will be required to change their password. It is recommended that you omit this value and allow the default value to be set unless you know the last time the user changed their password.

users[x].preferredLanguages [Array<String>] Optional

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

users[x].registrations [Array] Optional

The list of registrations for the User.

users[x].registrations[x].applicationId [UUID] Required

The Id of the Application that this registration is for.

users[x].registrations[x].cleanSpeakId [UUID] Optional

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

users[x].registrations[x].data [Object] Optional

An object that can hold any information about the User for this registration that should be persisted.

users[x].registrations[x].id [UUID] Optional defaults to secure random UUID

The Id of this registration. If not specified a secure random UUID will be generated.

users[x].registrations[x].insertInstant [Long] Optional defaults to now

The instant that this registration was created.

users[x].registrations[x].lastLoginInstant [Long] Optional

The instant that the User last logged into the Application for this registration.

users[x].registrations[x].preferredLanguages [Array<String>] Optional

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. See Locales.

users[x].registrations[x].roles [Array<String>] Optional

The list of roles that the User has for this registration.

users[x].registrations[x].username [String] Optional

The username of the User for this registration only.

users[x].registrations[x].usernameStatus [String] Optional defaults to ACTIVE

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

This state is managed by CleanSpeak, it may be changed by setting it on this request.

users[x].registrations[x].verified [Boolean] Optional defaults to false

Set this value to true in order to mark this registration as verified.

users[x].salt [String] Optional

The User’s password salt. Required if encryptionScheme is provided. Empty string is allowed.

When using any of the FusionAuth provided password encryption schemes, the incoming value is expected to be a Base64 encoded string of UTF-8 bytes. If your salt is stored as a plain string, you will need to Base64 encode it prior to import.

users[x].tenantId [UUID] Optional

The User’s tenant Id. If more than one tenant exists and you do not provide the X-FusionAuth-TenantId HTTP header or use API key to indicate which Tenant this request is for then this field will be required to complete the request.

When an API key is used that is locked to a Tenant or the tenant X-FusionAuth-TenantId HTTP header is provided this field is ignored.

users[x].timezone [String] Optional

The User’s preferred timezone. The string must be in an IANA time zone format.

users[x].twoFactorDelivery [String] Optional defaults to None

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

  When using TextMessage the User will also need a valid mobilePhone.

users[x].twoFactorEnabled [Boolean] Optional defaults to false

Determines if the User has two factor authentication enabled for their account or not.

See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API.

users[x].twoFactorSecret [String] Optional

The Base64 encode secret used to generate Two Factor verification codes.

You may optionally use value provided in the secret field returned by the Two Factor Secret API instead of generating this value yourself.

Unless you are using TextMessage as your delivery type, ensure you are able to share the secret with the User before enabling Two Factor authentication. Beginning in version 1.17.0, if you do create a User with TextMessage set as the twoFactorDelivery type and you omit this value, the secret will be generated for you. The secret can be generated because it is not necessary to share the secret with the User for this delivery method.

When using None as the twoFactorDelivery this value will be required.

users[x].username [String] Optional

The username of the User.

users[x].usernameStatus [String] Optional defaults to ACTIVE

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

This state is managed by CleanSpeak, it may be changed by setting it on this request.

users[x].verified [Boolean] Optional defaults to false

Set this value to true in order to mark the user as having a verified email address.

validateDbConstraints [Boolean] Optional defaults to false

Set this value to true in order to perform additional validation of the request.

The import request is intended to be used to populate the initial set of users, this means FusionAuth does not expect to find duplicate users in the database. If a duplicate is encountered a 500 will be returned without this additional validation.

If you intend to use this API with existing users in FusionAuth set this value to true to request additional validation be performed on the input request and a 400 response will be returned with JSON body indicating the duplicate values encountered.

Setting this value to true will dramatically decrease the performance of this request. If importing large numbers of users in a single request you may need to increase request timeouts to ensure this request does not timeout before it has completed.

{
  "users": [
    {
      "active": true,
      "birthDate": "1976-05-30",
      "data": {
        "displayName": "Johnny Boy",
        "favoriteColors": [
          "Red",
          "Blue"
        ]
      },
      "email": "example@fusionauth.io",
      "encryptionScheme": "salted-sha256",
      "expiry": 1571786483322,
      "factor": 24000,
      "firstName": "John",
      "fullName": "John Doe",
      "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
      "insertInstant": 1331449200000,
      "lastName": "Doe",
      "memberships": [{
        "data": {
          "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
        },
        "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5"
      }],
      "middleName": "William",
      "mobilePhone": "303-555-1234",
      "password": "5ac152b6f8bdb8bb12959548d542cb237c4a730064bf88bbb8dd6e204912baad",
      "passwordChangeRequired": false,
      "preferredLanguages": [
        "en",
        "fr"
      ],
      "registrations": [
        {
          "applicationId": "00000000-0000-0000-0000-000000000002",
          "data": {
            "birthplace": "Bremen"
          },
          "insertInstant": 1331449200000,
          "preferredLanguages": [
            "de"
          ],
          "roles": [
            "moderator"
          ],
          "username": "Mausebär",
          "verified": true
        }
      ],
      "salt": "NDdiYWZkZDMtYjk5ZC00ZmZkLWE1YmUtZTQxNGM4MDkwNWYw",
      "timezone": "America/Denver",
      "twoFactorEnabled": false,
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true
    }
  ]
}

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

refreshTokens [Array] Required

The list of refresh tokens to import.

refreshTokens[x].applicationId [UUID] Required

The unique Application Id that corresponds to the User Registration for this refresh token.

metaData.device.description [String] Optional

A human readable description of the device represented by the device parameter.

metaData.device.lastAccessedAddress [String] Optional

The IP address of this login request.

metaData.device.name [String] Optional

A human readable name of the device represented by the device parameter.

metaData.device.type [String] Optional

The type of device represented by the device parameter. The following types may be specified:

• BROWSER

• DESKTOP

• LAPTOP

• MOBILE

• OTHER

• SERVER

• TABLET

• TV

• UNKNOWN

refreshTokens[x].startInstant [String] Required

The instant of the start of this token. This value will be used to calculate the token expiration.

refreshTokens[x].token [String] Required

The string representation of the refresh token.

refreshTokens[x].userId [UUID] Required

The unique user Id of the refresh token owner.

validateDbConstraints [Boolean] Optional defaults to false

Set this value to true in order to perform additional validation of the request. This validation includes, among other things, confirming that a user exists and is registered for the application which this refreshToken was created for.

If this is false, any errors such as duplicated refresh token values will return a 500 error without any additional messages. If this is true, additional validation will be performed on the input request and a 400 response will be returned with JSON body indicating duplicate values or other error conditions encountered.

Setting this value to true will dramatically decrease the performance of this request. If importing large numbers of tokens in a single request you may need to increase request timeouts to ensure this request does not timeout before it has completed.

{
  "refreshTokens": [{
    "applicationId": "18a054da-f72d-480d-8da5-1f17d63bda87",
    "metaData": {
      "device": {
        "description":  "My refresh token imported from Umbrella Corp.",
        "lastAccessedAddress": "42.42.42.42",
        "lastAccessedInstant" : 1598315358855,
        "name" : "John's iPad",
        "type" : "TABLET"
      }
    },
    "startInstant": 1598315358855,
    "token": "YRjxLpsjRqL7zYuKstXogqioA_P3Z4fiEuga0NCVRcDSc8cy_9msxg",
    "userId": "e2b25780-fe20-4a69-ab6f-5e84744bc959"
  }]
}

Request Parameters

ids [UUID] Optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users. Using this parameter is mutually exclusive with the queryString field and is not paginated or sorted using the sortFields field.

numberOfResults [Integer] Optional defaults to 25

The number of search results to return. Used for pagination.

queryString [String] Optional

A query string that is used to search for Users. Using this parameter is mutually exclusive with the ids field.

Database search limits effective queries to single search terms that may match the following fields on the User:

• firstName

• lastName

• fullName

• email

• username

  The search matches against all of these fields and any user with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of * will match all records.

startRow [Integer] Optional defaults to 0

The start row within the search results to return. Used for pagination.

sortFields [Array] Optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

sortFields[x].name [String] Required

The name of the field to sort.

Required if sortFields is provided.

The following field names are supported for the database search engine:

• birthDate

• email

• fullName

• id

• insertInstant

• lastLoginInstant

• login

• tenantId

• username

sortFields[x].order [String] Optional defaults to asc

The order to sort the specified field. Possible values are:

• asc

• desc

Request Body

search.ids [UUID] Optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users. Using this parameter is mutually exclusive with the queryString field and is not paginated or sorted using the sortFields field.

search.numberOfResults [Integer] Optional defaults to 25

The number of search results to return. Used for pagination.

search.queryString [String] Optional

A query string that is used to search for Users. Using this parameter is mutually exclusive with the ids field.

Database search limits effective queries to single search terms that may match the following fields on the User:

• firstName

• lastName

• fullName

• email

• username

  The search matches against all of these fields and any user with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of * will match all records.

search.startRow [Integer] Optional defaults to 0

The start row within the search results to return. Used for pagination.

search.sortFields [Array] Optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

search.sortFields[x].name [String] Required

The name of the field to sort.

Required if sortFields is provided.

The following field names are supported for the database search engine:

• birthDate

• email

• fullName

• id

• insertInstant

• lastLoginInstant

• login

• tenantId

• username

search.sortFields[x].order [String] Optional defaults to asc

The order to sort the specified field. Possible values are:

• asc

• desc

{
  "search": {
    "ids": ["a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9", "00000000-0000-0001-0000-000000000000"]
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "@fusionauth.io",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "piper",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "*",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Request Parameters

ids [UUID] Optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users. Using this parameter is mutually exclusive with the query and queryString fields and is not paginated or sorted using sortFields field.

Using this parameter will not hit the Elasticsearch index, instead it will cause users to be retrieved by Id only.

numberOfResults [Integer] Optional defaults to 25

The number of search results to return. Used for pagination.

query [String] Optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

queryString [String] Optional

The Elasticsearch query string that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using %20 for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the * wildcard.

You may search against specific fields like so: email:*fusionauth.io. This will match only users with a fusionauth.io email address. You may find the available fields for matching by retrieving the Elasticsearch mapping.

startRow [Integer] Optional defaults to 0

The start row within the search results to return. Used for pagination.

sortFields [Array] Optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

sortFields[x].missing [String] Optional defaults to _last

The value to substitute if this field is not defined. Two special values may be used:

• _first When the field is not defined sort this record first.

• _last When the field is not defined sort this record last.

sortFields[x].name [String] Optional

The name of the field to sort.

Required if sortFields is provided.

Due to how the search index is structured not all fields on the user are sortable. The following field names are currently supported.

• birthDate

• email

• fullName

• id  Available since 1.13.0

• insertInstant

• lastLoginInstant   Available since 1.13.0

• login

• registrations.applicationId   Available since 1.13.0

• registrations.id   Available since 1.13.0

• registrations.insertInstant   Available since 1.13.0

• registrations.lastLoginInstant   Available since 1.13.0

• registrations.roles   Available since 1.13.0

• tenantId

• username

sortFields[x].order [String] Optional defaults to asc

The order to sort the specified field. Possible values are:

• asc

• desc

Request Body

search.ids [UUID] Optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users. Using this parameter is mutually exclusive with the query and queryString fields and is not paginated or sorted using sortFields field.

Using this parameter will not hit the Elasticsearch index, instead it will cause users to be retrieved by Id only.

search.numberOfResults [Integer] Optional defaults to 25

The number of search results to return. Used for pagination.

search.query [String] Optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the search.query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

search.queryString [String] Optional

The Elasticsearch query string that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using %20 for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the * wildcard.

You may search against specific fields like so: email:*fusionauth.io. This will match only users with a fusionauth.io email address. You may find the available fields for matching by retrieving the Elasticsearch mapping.

search.startRow [Integer] Optional defaults to 0

The start row within the search results to return. Used for pagination.

search.sortFields [Array] Optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

search.sortFields[x].missing [String] Optional defaults to _last

The value to substitute if this field is not defined. Two special values may be used:

• _first When the field is not defined sort this record first.

• _last When the field is not defined sort this record last.

search.sortFields[x].name [String] Optional

The name of the field to sort.

Required if sortFields is provided.

Due to how the search index is structured not all fields on the user are sortable. The following field names are currently supported.

• birthDate

• email

• fullName

• id  Available since 1.13.0

• insertInstant

• lastLoginInstant   Available since 1.13.0

• login

• registrations.applicationId   Available since 1.13.0

• registrations.id   Available since 1.13.0

• registrations.insertInstant   Available since 1.13.0

• registrations.lastLoginInstant   Available since 1.13.0

• registrations.roles   Available since 1.13.0

• tenantId

• username

search.sortFields[x].order [String] Optional defaults to asc

The order to sort the specified field. Possible values are:

• asc

• desc

{
  "search": {
    "ids": ["a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9", "00000000-0000-0001-0000-000000000000"]
  }
}

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "bool": {
              "must": [
                {
                  "match": {
                    "registrations.applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32"
                  }
                },
                {
                  "match": {
                    "registrations.verified": false
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
}

{
  "search": {
    "numberOfResults": 50,
    "query": "{\"bool\":{\"must\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"3c219e58-ed0e-4b18-ad48-f4f92793ae32\"}},{\"match\":{\"registrations.verified\":false}}]}}}}]}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "bool" : {
    "must" : [ [ {
      "nested" : {
        "path" : "registrations",
        "query" : {
          "bool" : {
            "must" : [ {
              "match" : {
                "registrations.applicationId" : "c50329fa-93e5-4618-8d9f-73d0ab069a54"
              }
            }, {
              "match" : {
                "registrations.roles" : "admin"
              }
            } ]
          }
        }
      }
    } ] ]
  }
}

{
  "search": {
    "numberOfResults": 50,
    "query": "{\"bool\":{\"must\":[[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"c50329fa-93e5-4618-8d9f-73d0ab069a54\"}},{\"match\":{\"registrations.roles\":\"admin\"}}]}}}}]]}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "query":"{\"match\":{\"email\":{\"query\":\"dinesh@fusionauth.io\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "query":"{\"match\":{\"data.userMigrated\":{\"query\":\"true\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "bool": {
    "must": [{
      "nested": {
        "path": "registrations",
        "query": {
          "range": {
            "registrations.data.minprice": {
              "gte": 50000,
              "lte": 100000
            }
          }
        }
      }
    }]
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "email:*@fusionauth.io",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "memberships.groupId:7f318a9d-3de4-4ded-9b53-1d97fd730868",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 50,
    "queryString": "tenantId:39666465-6535-3731-3139-666363356438",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Response Body

total [Long]

The number of users that matched the search criteria. The number of results in the response will be equal to the numberOfResults provided on the request, if not provided the default number of results will be returned.

users [Array]

The list of Users.

users[x].active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

users[x].birthDate [String]

YYYY-MM-DD formatted date of the User’s birth.

users[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

users[x].connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

users[x].data [Object]

An object that can hold any information about the User that should be persisted.

users[x].email [String]

The User’s email address.

users[x].encryptionScheme [String] Available since 1.20.1

The encryption scheme used to hash the password for this user. This value is only returned when the user is retrieved using an API key.

users[x].expiry [Long]

The expiration instant of the User’s account. After this instant is reached, the User’s account will automatically be deactivated.

users[x].firstName [String]

The first name of the User.

users[x].fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

users[x].id [UUID]

The User’s unique Id.

users[x].imageUrl [String]

The URL that points to an image file that is the User’s profile image.

users[x].insertInstant [Long]

The instant when user was created.

users[x].lastLoginInstant [Long]

The instant when the User logged in last.

users[x].lastName [String]

The User’s last name.

users[x].memberships [Array]

The list of memberships for the User.

users[x].memberships[x].data [Object]

An object that can hold any information about the User for this membership that should be persisted.

users[x].memberships[x].groupId [UUID]

The Id of the Group of this membership.

users[x].memberships[x].id [UUID]

The unique Id of this membership.

users[x].memberships[x].insertInstant [Long]

The instant that the membership was created.

users[x].middleName [String]

The User’s middle name.

users[x].mobilePhone [String]

The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User.

users[x].passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

users[x].passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

users[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

users[x].registrations [Array]

The list of registrations for the User.

users[x].registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

users[x].registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

users[x].registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

users[x].registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

users[x].registrations[x].id [UUID]

The Id of this registration.

users[x].registrations[x].insertInstant [Long]

The instant that this registration was created.

users[x].registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

users[x].registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. See Locales.

users[x].registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

users[x].registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

users[x].registrations[x].tokens [Map<String,String>] Available since 1.1.0

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

users[x].registrations[x].username [String]

The username of the User for this registration only.

users[x].registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

users[x].tenantId [UUID]

The Id of the Tenant that this User belongs to.

users[x].timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

users[x].twoFactorDelivery [String]

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

users[x].twoFactorEnabled [Boolean]

Determines if the User has two factor authentication enabled for their account or not.

users[x].username [String]

The username of the User.

users[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].verified [Boolean]

Whether or not the User’s email has been verified.

{
  "users": [
    {
      "active": true,
      "birthDate": "1976-05-30",
      "data": {
        "displayName": "Johnny Boy",
        "favoriteColors": [
          "Red",
          "Blue"
        ]
      },
      "email": "example@fusionauth.io",
      "expiry": 1571786483322,
      "firstName": "John",
      "fullName": "John Doe",
      "id": "00000000-0000-0001-0000-000000000000",
      "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
      "lastLoginInstant": 1471786483322,
      "lastName": "Doe",
      "memberships": [{
        "data": {
          "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
        },
        "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5",
        "id": "27218714-305e-4408-bac0-23e7e1ddceb6",
        "insertInstant": 1471786482322
      }],
      "middleName": "William",
      "mobilePhone": "303-555-1234",
      "passwordChangeRequired": false,
      "passwordLastUpdateInstant": 1471786483322,
      "preferredLanguages": [
        "en",
        "fr"
      ],
      "registrations": [
        {
          "applicationId": "10000000-0000-0002-0000-000000000001",
          "data": {
            "displayName": "Johnny",
            "favoriteSports": [
              "Football",
              "Basketball"
            ]
          },
          "id": "00000000-0000-0002-0000-000000000000",
          "insertInstant": 1446064706250,
          "lastLoginInstant": 1456064601291,
          "preferredLanguages": [
            "en",
            "fr"
          ],
          "roles": [
            "user",
            "community_helper"
          ],
          "tokens": {
            "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
            "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
          },
          "username": "johnny123",
          "usernameStatus": "ACTIVE",
          "verified": true
        }
      ],
      "timezone": "America/Denver",
      "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
      "twoFactorEnabled": false,
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true
    }
  ]
}

Request Parameters

limit [Integer] Optional defaults to 10

This parameter indicates the maximum amount of logins to return for a single request.

offset [Integer] Optional defaults to 0

This parameter provides the offset into the result set. Generally speaking if you wish to paginate the results, you will increment this parameter on subsequent API request by the size of the limit parameter.

userId [UUID] Optional

This parameter will narrow the results to only logins for a particular user. When this parameter is omitted, the most recent logins for all of FusionAuth will be returned.

Response Body

logins [Array]

A list of recent logins.

logins[x].applicationId [UUID]

The unique Id of the application that is represented by this login record.

logins[x].applicationName [String]

The name of the application at the time this record was created.

logins[x].instant [Long]

The instant this login occurred.

logins[x].ipAddress [String]

The IP address if provided during the login request.

logins[x].loginId [String]

The User’s email address or username at the time of the login request.

logins[x].userId [UUID]

The unique Id of the user that is represented by this login record.

{
  "logins": [
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "applicationName": "PiedPiper",
      "instant": 1549493410058,
      "ipAddress": "42.42.42.42",
      "loginId": "jared@piedpiper.com",
      "userId": "4469bea7-8b10-4ad3-94f2-bc8df962b489"
    },
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "applicationName": "Acme Corp.",
      "instant": 1549485962036,
      "ipAddress": "42.42.42.42",
      "loginId": "admin@acme.com",
      "userId": "4469bea7-8b10-4ad3-94f2-bc8df962b489"
    },
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "applicationName": "Support Portal",
      "instant": 1549387234024,
      "ipAddress": "42.42.42.42",
      "loginId": "bob@gmail.com",
      "userId": "6a802b03-17e3-404f-830f-ea5c30ca50df"
    }
  ]
}

Request Parameters

verificationId [String] Required

The verification Id generated by FusionAuth used to verify the User’s account is valid by ensuring they have access to the provided email address.

Request Parameters

email [String] Required

The email address used to uniquely identify the User.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Resend the verification email using an API key

Request Parameters

email [String] Required

The email address used to uniquely identify the User.

sendVerifyEmail [Boolean] Optional defaults to true

If you would only like to generate a new verificationId and return it in the JSON body without FusionAuth attempting to send the User an email set this optional parameter to false.

This may be useful if you need to integrate the Email Verification process using a third party messaging service.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Response Body

verificationId [String]

The email verification Id that was generated by this API request. This identifier may be used by the Verify a User’s Email API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned.

{
  "verificationId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

loginId [String] Required

The login identifier of the user. The login identifier can be either the email or the username. The username is not case sensitive.

{
  "loginId": "example@fusionauth.io"
}

Start the forgot password workflow using an API key

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

changePasswordId [String] Optional

The optional change password Id to be used on the Change a User’s Password API.

It is recommended to omit this parameter and allow FusionAuth to generate the identifier. Use this parameter only if you must supply your own value for integration into existing systems.

loginId [String] Required

The login identifier of the user. The login identifier can be either the email or the username. The username is not case sensitive.

sendForgotPasswordEmail [Boolean] Optional defaults to true

Whether or not calling this API should attempt to send the user an email using the Forgot Password Email Template. Setting this to false will skip the email attempt and only set the changePasswordId for the user.

{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4",
  "loginId": "example@fusionauth.io",
  "sendForgotPasswordEmail": false
}

Response Body

changePasswordId [String]

The change password Id that was generated by this API request. This identifier may be used by the Change Password API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned.

{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

Request Parameters

changePasswordId [String] Required

The changePasswordId that is used to identity the user after the Start Forgot Password workflow has been initiated.

If this changePasswordId was sent via an email to the User by FusionAuth during User create in order to set up a new password, or as part of a Forgot Password request, then successful use of this identifier to change the User’s password will implicitly complete Email Verification if not already verified.

Request Body

currentPassword [String] Optional

The User’s current password. When this parameter is provided the current password will be verified to be correct.

password [String] Required

The User’s new password.

{
  "currentPassword": "too many secrets",
  "password": "Setec Astronomy"
}

Changes a User’s password using an email address or username.

This usage requires and API key and allows you to change any user’s password if you have a unique email or username.

Request Headers

X-FusionAuth-TenantId [String] Optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

currentPassword [String] Optional

The User’s current password. When this parameter is provided the current password will be verified to be correct.

loginId [String] Required

The login identifier of the user. The login identifier can be either the email or the username. The username is not case sensitive.

When this value is provided it should be in place of the changePasswordId request parameter. If both the changePasswordId and loginId are provided on the request, the changePasswordId will take precedence.

password [String] Required

The User’s new password.

{
  "currentPassword": "too many secrets",
  "loginId": "cosmo@playtronics.com",
  "password": "Setec Astronomy"
}

Changes a User’s password using a JWT

This API will use a JWT as authentication. See JWT Authentication for examples of how you can send the JWT to FusionAuth.

A common use case for using this API with a JWT will be if you want to allow the user to change their own password. Specifically if you are attempting to perform this request in a frontend browser that cannot store an API key.

Because changing a User’s password will revoke all existing refresh tokens if you allow the user to change their password they will need to re-authenticate to stay logged into your application if you are utilizing JWTs and Refresh Tokens.

For this reason, this API will return a oneTimePassword that is intended to be used programatically after a Change Password request completes to keep the user logged in and provide a better user experience. A successful login will return you a new access token (JWT) and a refresh token. This will allow you to make the change password workflow seamless to the user.

Request Body

currentPassword [String] Required

The User’s current password. This is required when using a JWT to change your password.

password [String] Required

The User’s new password.

refreshToken [String] Optional

The user’s existing refresh token. If you have access to your current refresh token, it can be provided in the request body using this parameter. If the refresh_token cookie also exists and is present on the request it will take precedence over this parameter.

This parameter is used to determine if the oneTimePassword that is returned from this API will be eligible to request a refresh token when used by the Login API. If this parameter is not provided and no cookie is found on the request, a refresh token will not be provided on the Login response when using the returned oneTimePassword.

{
  "currentPassword": "too many secrets",
  "password": "Setec Astronomy"
}