Users

Overview

This page contains all of the APIs for managing users.

Create a User

This API is used to create a new User.

Request

Create a User with a randomly generated Id

POST /api/user

Create a User with the provided unique Id

POST /api/user/{userId}

Request Headers

X-FusionAuth-TenantIdString

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

userIdUUIDDefaults 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

applicationIdUUIDAvailable since 1.30.0

An optional Application Id. When this value is provided, it will be used to resolve an application specific email template if you have configured transactional emails such as setup password, email verification and others.

If not provided, only the tenant configuration will be used when resolving email templates.

disableDomainBlockBooleanDefaults to falseAvailable since 1.30.0

A tenant has the option to configure one or more email domains to be blocked in order to restrict email domains during user create or update.

Setting this property equal to true will override the tenant configuration. See tenant.registrationConfiguration.blockedDomains in the Tenant API.

sendSetPasswordEmailBooleanDefaults to false

If true, FusionAuth will send the User an email asking them to set their password. The Email Template that is used is the one specified in the setPasswordEmailTemplateId .

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

If you have also enabled email verification and do not skip verification with 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 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.

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

Setting this to true will set the user.verified field to true as well.

user.birthDateString

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

user.dataObject

An object that can hold any information about a User that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

user.data.emailString

This field will be used as the email address if no user.email field is found. This field may be modified by advanced registration forms or the API. Setting this value to another account’s email address allows that account to, in some cases, access information about this user.

If user richard has a user.data.email with a value of dinesh@fusionauth.io, whoever controls dinesh@fusionauth.io has elevated access to the richard account. That user can now reset the password on the richard account, for example. This functionality may be useful in certain scenarios, such as when accounts must share an email address. Think through the security ramifications before using this feature.

This feature was removed in version 1.26.0 and added back in in 1.27.2.

user.emailString

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

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
salted-pbkdf2-hmac-sha256-512 Available since 1.34.0
bcrypt
phpass-md5 Available since 1.45.0
phpass-sha512Available since 1.45.0

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

user.expiryLong

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

user.factorString

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

The first name of the User.

user.fullNameString

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

user.imageUrlString

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

user.lastNameString

The User’s last name.

user.middleNameString

The User’s middle name.

user.membershipsArray

The list of memberships for the User.

user.memberships[x].dataObject

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

user.memberships[x].groupIdUUIDrequired

The Id of the Group of this membership.

user.memberships[x].idUUIDDefaults to secure random UUID

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

user.mobilePhoneString

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

user.parentEmailStringAvailable 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.passwordString

The User’s plain text 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.passwordChangeRequiredBooleanDefaults to false

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

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

The maximum number of allowed preferred languages is 20.

user.timezoneString

The User’s preferred timezone. The string must be in an IANA time zone format. For example: America/Denver or US/Mountain.

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactor.methods[x].secretString

A base64 encoded secret.

This field is required when method is authenticator.

user.twoFactorDeliveryStringDefaults to NoneDEPRECATED

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.

Removed in 1.26.0

user.twoFactorEnabledBooleanDefaults to falseDEPRECATED

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.

Removed in 1.26.0

user.twoFactorSecretStringDEPRECATED

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.

Removed in 1.26.0

user.usernameString

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

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.

Example Request JSON

{
  "applicationId": "368994e6-ba8a-49b5-8446-7b99ab1fffdf",
  "disableDomainBlock": false,
  "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",
    "memberships": [
      {
        "data": {
          "externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc"
        },
        "groupId": "2cb5c83f-53ff-4d16-88bd-c5e3802111a5"
      }
    ],
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "password": "supersecret",
    "passwordChangeRequired": false,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "timezone": "America/Denver",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "secret": "aGVsbG8Kd29ybGQKaGVsbG8gaGVsbG8=",
          "method": "authenticator"
        },
        {
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "method": "email",
          "email": "example@fusionauth.io"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123"
  }
}

Response

The response for this API contains the User that was just created. The password, salt and other sensitive fields will not be returned on the API response.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body

tokenStringAvailable since 1.16.0

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

tokenExpirationInstantLongAvailable since 1.33.0

The instant the token will expire. If the response does not contain a token , this field will also be omitted from the response.

emailVerificationIdStringAvailable since 1.27.0

An email verification Id. When present, this will represent the user’s current email verification Id.

When using FormField verification strategy, this is the first part of the pair of verification Ids, and the emailVerificationOneTimeCode is the second part. When ClickableLink is the verification strategy, this value is sensitive in that this value by itself can be used to verify the user’s email address.

When ClickableLink is the verification strategy, this is the value that will have been emailed to the user in order to complete verification. If you have not configured SMTP, you may optionally use this value to use an out of band transport such as your own email service.

Prior to version 1.49.0, this value was only returned when using FormField verification strategy. Beginning in 1.49.0 the value is always returned when available.

emailVerificationOneTimeCodeStringAvailable since 1.49.0

An email one time code that will be paired with the emailVerificationId .

When FormField is the verification strategy, this is the value that will have been emailed to the user in order to complete verification. If you have not configured SMTP, you may optionally use this value to use an out of band transport such as your own email service.

This value will only be present when using the FormField verification strategy. When present, this is the value the user will need to enter to complete email verification.

user.activeBoolean

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

user.birthDateString

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

user.breachedPasswordLastCheckedInstantLong

The instant this user’s password was last checked to determine if it is compromised.

user.connectorIdUUIDAvailable since 1.18.0

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

user.cleanSpeakIdUUID

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

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

user.data.emailString

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

user.emailString

The User’s email address.

user.expiryLong

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

user.firstNameString

The first name of the User.

user.fullNameString

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

user.idUUID

The User’s unique Id.

user.imageUrlString

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

user.insertInstantLong

The instant when the user was created.

user.lastLoginInstantLong

The instant when the User logged in last.

user.lastNameString

The User’s last name.

user.lastUpdateInstantLong

The instant when the User was last updated.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable 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 will only remain until the child is claimed by a parent.

user.passwordChangeRequiredBoolean

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

user.passwordLastUpdateInstantLong

The instant that the User last changed their password.

user.preferredLanguagesArray<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.registrationsArray

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationTokenString

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

user.registrations[x].cleanSpeakIdUUID

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

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

user.registrations[x].idUUID

The Id of this registration.

user.registrations[x].insertInstantLong

The instant that this registration was created.

user.registrations[x].lastLoginInstantLong

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

user.registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

user.registrations[x].timezoneString

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

user.registrations[x].tokensMap<String,StringDEPRECATED

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.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].usernameString

The username of the User for this registration only. This is for display purposes and cannot be used to login.

user.registrations[x].usernameStatusString

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

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

For additional information, see these tutorials:

user.registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

user.tenantIdUUID

The Id of the Tenant that this User belongs to.

user.timezoneString

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

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].idString

The unique Id of the method.

user.twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactorDeliveryStringDEPRECATED

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

The possible values are:

None
TextMessage

Removed in 1.26.0

user.twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0

user.usernameString

The username of the User.

user.usernameStatusString

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

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

For additional information, see these tutorials:

user.verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Note that this value is immutable and will only represent the first time the email was verified. If you enable re-verification on email change, this value will not change and will only represent the initial verification.

Example Response JSON

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxVU5ON0pIUVc4X21ROHBTaWZKbzBXekdybDlTbTRnIn0.eyJleHAiOjE1ODY4ODQzNzksImlhdCI6MTU4Njg4NDMxOSwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlVTRVJfQ1JFQVRFIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.Z1jV8xDcayZZDBdLRVd2fIyowhstRI4Dgk7_u2XFerc",
  "user": {
    "active": true,
    "breachedPasswordLastCheckedInstant": 1471786483322,
    "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",
        "username": "johnny123",
        "usernameStatus": "ACTIVE",
        "verified": true,
        "verifiedInstant": 1698772159415
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1698772159415
  }
}

Retrieve a User

Retrieve a User by Email Verification Id

GET /api/user?verificationId={verificationId}

Request Parameters

verificationIdStringrequired

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

Request Headers

X-FusionAuth-TenantIdString

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

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

Retrieve a User using a JWT

GET /api/user

Deprecated since 1.50.0

Request Headers

X-FusionAuth-TenantIdString

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

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

Response

The response for this API contains the User.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

emailVerificationIdStringAvailable since 1.27.0

An email verification Id. When present, this will represent the user’s current email verification Id.

Prior to version 1.49.0, this value was only returned when using FormField verification strategy. Beginning in 1.49.0 the value is always returned when available.

emailVerificationOneTimeCodeStringAvailable since 1.49.0

An email one time code that will be paired with the emailVerificationId .

This value will only be present when using the FormField verification strategy. When present, this is the value the user will need to enter to complete email verification.

registrationVerificationIdsMap<UUID, List<String>>Available since 1.27.0

A map of registration verification Id keyed by the application. When present, this will represent the user’s current registration verification Ids.

When using FormField verification strategy, this is the first part of the pair of verification Ids, and the one time code in the registrationVerificationOneTimeCodes map is the second part. When ClickableLink is the verification strategy, this value is sensitive in that this value by itself can be used to verify the user’s registration.

When ClickableLink is the verification strategy, you may optionally use this value to use an out of band transport such as your own email service.

Prior to version 1.49.0, this value was only returned when using FormField verification strategy. Beginning in 1.49.0 the value is always returned when available.

registrationVerificationOneTimeCodesMap<UUID, List<String>>Available since 1.49.2

A registration one time code that will be paired with the verification Id in the registrationVerificationIds map.

When FormField is the verification strategy, you may optionally use this value to use an out of band transport such as your own email service.

This value will only be present when using the FormField verification strategy. When present, this is the value the user will need to enter to complete registration verification.

user.activeBoolean

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

user.birthDateString

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

user.breachedPasswordLastCheckedInstantLong

The instant this user’s password was last checked to determine if it is compromised.

user.connectorIdUUIDAvailable since 1.18.0

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

user.cleanSpeakIdUUID

user.dataObject

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

user.data.emailString

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

user.emailString

The User’s email address.

user.encryptionSchemeStringAvailable 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.expiryLong

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

user.firstNameString

The first name of the User.

user.fullNameString

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

user.idUUID

The User’s unique Id.

user.imageUrlString

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

user.insertInstantLong

The instant when the user was created.

user.lastLoginInstantLong

The instant when the User logged in last.

user.lastNameString

The User’s last name.

user.lastUpdateInstantLong

The instant when the User was last updated.

user.membershipsArray

The list of memberships for the User.

user.memberships[x].dataObject

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

user.memberships[x].groupIdUUID

The Id of the Group of this membership.

user.memberships[x].idUUID

The unique Id of this membership.

user.memberships[x].insertInstantLong

The instant that the membership was created.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable 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 will only remain until the child is claimed by a parent.

user.passwordChangeRequiredBoolean

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

user.passwordLastUpdateInstantLong

The instant that the User last changed their password.

user.preferredLanguagesArray<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.registrationsArray

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationTokenString

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

user.registrations[x].cleanSpeakIdUUID

user.registrations[x].dataObject

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

user.registrations[x].idUUID

The Id of this registration.

user.registrations[x].insertInstantLong

The instant that this registration was created.

user.registrations[x].lastLoginInstantLong

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

user.registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

user.registrations[x].timezoneString

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

user.registrations[x].tokensMap<String,StringDEPRECATED

A map that contains tokens returned from identity providers.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].usernameString

The username of the User for this registration only. This is for display purposes and cannot be used to login.

user.registrations[x].usernameStatusString

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

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

For additional information, see these tutorials:

user.registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

user.tenantIdUUID

The Id of the Tenant that this User belongs to.

user.timezoneString

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].idString

The unique Id of the method.

user.twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactorDeliveryStringDEPRECATED

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

The possible values are:

None
TextMessage

Removed in 1.26.0

user.twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0

user.usernameString

The username of the User.

user.usernameStatusString

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

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

For additional information, see these tutorials:

user.verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Example Response JSON

{
  "user": {
    "active": true,
    "breachedPasswordLastCheckedInstant": 1471786483322,
    "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",
        "username": "johnny123",
        "usernameStatus": "ACTIVE",
        "verified": true,
        "verifiedInstant": 1698772159415
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1698772159415
  }
}

Update a User

This API is used to update an existing User.

You must specify all of the properties of the User when calling this API with the PUT HTTP method. When used with PUT, this API doesn’t merge the existing User and your new data. It replaces the existing User with your new data.

Utilize the PATCH HTTP method to send specific changes to merge into an existing User.

If you specify a new password for the User, it will be encrypted and stored. However, if you do not provide a new password, the User’s old password will be preserved. This is the only field that is merged during an update using the PUT method.

Request

Update the User with the given Id

PUT /api/user/{userId}

PATCH /api/user/{userId}

When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902] or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

Request Parameters

userIdUUIDrequired

The Id of the User to update.

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

applicationIdUUIDAvailable since 1.30.0

If not provided, only the tenant configuration will be used when resolving email templates.

disableDomainBlockBooleanDefaults to falseAvailable since 1.30.0

A tenant has the option to configure one or more email domains to be blocked in order to restrict email domains during user create or update.

Setting this property equal to true will override the tenant configuration. See tenant.registrationConfiguration.blockedDomains in the Tenant API.

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

Setting this to true will set the user.verified field to true as well.

user.birthDateString

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

user.dataObject

An object that can hold any information about a User that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

user.data.emailString

This feature was removed in version 1.26.0 and added back in in 1.27.2.

user.emailString

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

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
salted-pbkdf2-hmac-sha256-512 Available since 1.34.0
bcrypt
phpass-md5 Available since 1.45.0
phpass-sha512Available since 1.45.0

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 Custom Password Hashing section for more information.

user.expiryLong

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

user.factorString

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

The first name of the User.

user.fullNameString

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

user.imageUrlString

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

user.lastNameString

The User’s last name.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable since 1.7.0

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

The User’s plain text 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.passwordChangeRequiredBooleanDefaults to false

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

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

The maximum number of allowed preferred languages is 20.

user.timezoneString

The User’s preferred timezone. The string must be in an IANA time zone format. For example: America/Denver or US/Mountain.

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactor.methods[x].secretString

A base64 encoded secret.

This field is required when method is authenticator.

user.twoFactorDeliveryStringDefaults to NoneDEPRECATED

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.

Removed in 1.26.0

user.twoFactorEnabledBooleanDefaults to falseDEPRECATED

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.

Removed in 1.26.0

user.twoFactorSecretStringDEPRECATED

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.

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.

Removed in 1.26.0

user.usernameString

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

user.usernameStatusString

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.

Example Request JSON

{
  "application": "368994e6-ba8a-49b5-8446-7b99ab1fffdf",
  "disableDomainBlock": false,
  "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",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "secret": "aGVsbG8Kd29ybGQKaGVsbG8gaGVsbG8=",
          "method": "authenticator"
        },
        {
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123"
  }
}

Response

The response for this API contains the User that was updated. The password hash and other sensitive fields are never returned on the API response.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to update doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body

emailVerificationIdStringAvailable since 1.27.0

An email verification Id. When present, this will represent the user’s current email verification Id.

Prior to version 1.49.0, this value was only returned when using FormField verification strategy. Beginning in 1.49.0 the value is always returned when available.

emailVerificationOneTimeCodeStringAvailable since 1.49.0

An email one time code that will be paired with the emailVerificationId .

This value will only be present when using the FormField verification strategy. When present, this is the value the user will need to enter to complete email verification.

user.activeBoolean

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

user.birthDateString

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

user.breachedPasswordLastCheckedInstantLong

The instant this user’s password was last checked to determine if it is compromised.

user.connectorIdUUIDAvailable since 1.18.0

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

user.cleanSpeakIdUUID

user.dataObject

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

user.data.emailString

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

user.emailString

The User’s email address.

user.expiryLong

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

user.firstNameString

The first name of the User.

user.fullNameString

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

user.idUUID

The User’s unique Id.

user.imageUrlString

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

user.insertInstantLong

The instant when the user was created.

user.lastLoginInstantLong

The instant when the User logged in last.

user.lastNameString

The User’s last name.

user.lastUpdateInstantLong

The instant when the User was last updated.

user.membershipsArray

The list of memberships for the User.

user.memberships[x].dataObject

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

user.memberships[x].groupIdUUID

The Id of the Group of this membership.

user.memberships[x].idUUID

The unique Id of this membership.

user.memberships[x].insertInstantLong

The instant that the membership was created.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable 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 will only remain until the child is claimed by a parent.

user.passwordChangeRequiredBoolean

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

user.passwordLastUpdateInstantLong

The instant that the User last changed their password.

user.preferredLanguagesArray<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.registrationsArray

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationTokenString

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

user.registrations[x].cleanSpeakIdUUID

user.registrations[x].dataObject

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

user.registrations[x].idUUID

The Id of this registration.

user.registrations[x].insertInstantLong

The instant that this registration was created.

user.registrations[x].lastLoginInstantLong

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

user.registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

user.registrations[x].timezoneString

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

user.registrations[x].tokensMap<String,StringDEPRECATED

A map that contains tokens returned from identity providers.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].usernameString

The username of the User for this registration only. This is for display purposes and cannot be used to login.

user.registrations[x].usernameStatusString

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

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

For additional information, see these tutorials:

user.registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

user.tenantIdUUID

The Id of the Tenant that this User belongs to.

user.timezoneString

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].idString

The unique Id of the method.

user.twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactorDeliveryStringDEPRECATED

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

The possible values are:

None
TextMessage

Removed in 1.26.0

user.twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0

user.usernameString

The username of the User.

user.usernameStatusString

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

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

For additional information, see these tutorials:

user.verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Example Response JSON

{
  "user": {
    "active": true,
    "breachedPasswordLastCheckedInstant": 1471786483322,
    "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",
        "username": "johnny123",
        "usernameStatus": "ACTIVE",
        "verified": true,
        "verifiedInstant": 1698772159415
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1698772159415
  }
}

Delete a User

This API is used to delete a User. You must specify the Id of the User on the URI. You can also specify whether or not the User is soft or hard deleted. A soft delete deactivates the User. A hard delete permanently deletes a User’s data.

Soft deleted users are marked as inactive but not deleted from FusionAuth. Deactivated users have their data retained but they are unable to authenticate. Users who have been deactivated can be reactivated; see Reactivate a User for more.

The data of a User who has been hard deleted is permanently removed from FusionAuth. The User’s data cannot be restored via the FusionAuth API or the administrative user interface. If you need to restore the User’s data, you must retrieve it from a database backup.

Request

Deactivate a User (Soft Delete)

DELETE /api/user/{userId}

Permanently Delete a User

DELETE /api/user/{userId}?hardDelete=true

Request Parameters

userIdUUIDrequired

The Id of the User to delete.

hardDeleteBooleanDefaults 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 Headers

X-FusionAuth-TenantIdString

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

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

Response

This API does not return a JSON response body.

Response Codes

Code	Description
200	The request was successful.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Bulk Delete Users

This API is used to deactivate or delete multiple users in a single request.

This API has some limitations when FusionAuth is configured to use the database as the user search engine. These limitations are noted on the impacted request parameters below.

Request

Deactivate Users by User Id

DELETE /api/user/bulk?userId={userId}&userId={userId}

Deactivate Users by Search Query String

DELETE /api/user/bulk?queryString={queryString}&dryRun=false&limit=10000

Deactivate Users by Raw JSON Search Query

DELETE /api/user/bulk?query={query}&dryRun=false&limit=10000

Permanently Delete Users by User Id

DELETE /api/user/bulk?userId={userId}&userId={userId}&hardDelete=true

Permanently Delete Users by Search Query String

DELETE /api/user/bulk?queryString={queryString}&hardDelete=true&dryRun=false&limit=10000

Permanently Delete Users by Raw JSON Search Query

DELETE /api/user/bulk?query={query}&hardDelete=true&dryRun=false&limit=10000

Request Parameters

dryRunBooleanDefaults to false

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

hardDeleteBooleanDefaults to false

limitIntegerDefaults to 10,000Available since 1.48.0

The maximum number of users to delete in one call.

You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response.

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

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

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

FusionAuth adds wildcards to unscoped queryStrings in order to match the broadest set of results. Depending on the specifics of the system, a leading wildcard on a search term can significantly reduce search performance. In order to improve search performance, limit the search to a single field by specifying it in the queryString followed by a : to prevent the pre-processing by FusionAuth.

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

userIdUUID

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 Headers

X-FusionAuth-TenantIdString

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

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

Bulk delete using the request body. This allows for larger requests than are possible using request parameters.

DELETE /api/user/bulk

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

dryRunBooleanDefaults to false

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

hardDeleteBooleanDefaults to false

limitIntegerDefaults to 10,000Available since 1.48.0

The maximum number of users to delete in one call.

You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response.

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

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

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

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

userIdsArray

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

Example Request JSON searching by userIds

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

Example JSON for the query parameter to search for users with unverified registrations to a specific application

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

Example JSON searching by query for users with unverified registrations to a specific application

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

Example JSON for the query parameter to search for users with a specific role

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

Example JSON searching by query for users with with a specific role

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

Example Request JSON searching by queryString for users with an email address matching a pattern

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

Example Request JSON searching by queryString for users belonging to a specific group with a limit

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

Example Request JSON searching by queryString for users of a specific tenant. A global API key must be used, and you may not use the X-FusionAuth-TenantId header when the search parameters include tenantId

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

Response

The response for this API contains the information for the Users that were affected by the request.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body

dryRunBoolean

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

hardDeleteBoolean

Whether the requested action was deactivation or permanent deletion.

totalInteger

The count of affected Users.

userIdsArray<UUID>

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

Example Response JSON

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

Reactivate a User

This API is used to reactivate an inactive Users. You must specify the Id of the User on the URI.

Request

Reactivate the User

PUT /api/user/{userId}?reactivate=true

Request Parameters

userIdUUIDrequired

The Id of the User to reactivate.

Request Headers

X-FusionAuth-TenantIdString

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

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

Response

The response for this API contains the information for the User that was reactivated.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to update doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body

user.activeBoolean

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

user.birthDateString

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

user.breachedPasswordLastCheckedInstantLong

The instant this user’s password was last checked to determine if it is compromised.

user.connectorIdUUIDAvailable since 1.18.0

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

user.cleanSpeakIdUUID

user.dataObject

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

user.data.emailString

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

user.emailString

The User’s email address.

user.expiryLong

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

user.firstNameString

The first name of the User.

user.fullNameString

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

user.idUUID

The User’s unique Id.

user.imageUrlString

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

user.insertInstantLong

The instant when the user was created.

user.lastLoginInstantLong

The instant when the User logged in last.

user.lastNameString

The User’s last name.

user.lastUpdateInstantLong

The instant when the User was last updated.

user.membershipsArray

The list of memberships for the User.

user.memberships[x].dataObject

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

user.memberships[x].groupIdUUID

The Id of the Group of this membership.

user.memberships[x].idUUID

The unique Id of this membership.

user.memberships[x].insertInstantLong

The instant that the membership was created.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable 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 will only remain until the child is claimed by a parent.

user.passwordChangeRequiredBoolean

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

user.passwordLastUpdateInstantLong

The instant that the User last changed their password.

user.preferredLanguagesArray<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.registrationsArray

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationTokenString

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

user.registrations[x].cleanSpeakIdUUID

user.registrations[x].dataObject

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

user.registrations[x].idUUID

The Id of this registration.

user.registrations[x].insertInstantLong

The instant that this registration was created.

user.registrations[x].lastLoginInstantLong

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

user.registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

user.registrations[x].timezoneString

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

user.registrations[x].tokensMap<String,StringDEPRECATED

A map that contains tokens returned from identity providers.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].usernameString

The username of the User for this registration only. This is for display purposes and cannot be used to login.

user.registrations[x].usernameStatusString

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

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

For additional information, see these tutorials:

user.registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

user.tenantIdUUID

The Id of the Tenant that this User belongs to.

user.timezoneString

user.twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].idString

The unique Id of the method.

user.twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

user.twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

user.twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactorDeliveryStringDEPRECATED

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

The possible values are:

None
TextMessage

Removed in 1.26.0

user.twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0

user.usernameString

The username of the User.

user.usernameStatusString

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

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

For additional information, see these tutorials:

user.verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Example Response JSON

{
  "user": {
    "active": true,
    "breachedPasswordLastCheckedInstant": 1471786483322,
    "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",
        "username": "johnny123",
        "usernameStatus": "ACTIVE",
        "verified": true,
        "verifiedInstant": 1698772159415
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1698772159415
  }
}

Import Users

This API is used to bulk import multiple Users into FusionAuth. Each User must have at least an email or a username, and a password (plaintext or hash). If you don’t have the User’s password, you can set this field to a long random string and require the User to reset their password at their next login. This request is useful for migrating data from an existing database into FusionAuth. Additionally, you can provide an Id for each User inside the JSON User object of the request body. When using this API, the recommended batch size per request is dependent on deployment scale (note: 100,000 users per request is a reasonable batch size for a production capable deployment). After completing an import, you should reindex the Elasticsearch database as well.

You should not make multiple calls to this API in parallel. Multiple sequential calls to this API are fine.

Request

Import Multiple Users

POST /api/user/import

Request Headers

X-FusionAuth-TenantIdString

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

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. The password field (plaintext or hash) is also required.

Request Body

encryptionSchemeString

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
salted-pbkdf2-hmac-sha256-512 available since 1.34.0
salted-pbkdf2-hmac-sha512-512 available since 1.43.0
bcrypt
phpass-md5 available since 1.45.0
phpass-sha512 available since 1.45.0

factorInteger

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

usersArrayrequired

The list of Users to import.

users[x].activeBooleanDefaults 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].birthDateString

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

users[x].dataObject

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

user[x].data.emailString

This feature was removed in version 1.26.0 and added back in in 1.27.2.

users[x].emailString

The User’s email address.

users[x].encryptionSchemeString

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
salted-pbkdf2-hmac-sha256-512 available since 1.34.0
salted-pbkdf2-hmac-sha512-512 available since 1.43.0
bcrypt
phpass-md5 available since 1.45.0
phpass-sha512 available since 1.45.0

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 Custom Password Hashing section for more information.

users[x].expiryLong

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

users[x].factorString

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

The first name of the User.

users[x].fullNameString

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

users[x].idUUIDDefaults to secure random UUID

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

users[x].imageUrlString

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

users[x].insertInstantLongDefaults to now

The instant when the user was created.

users[x].lastNameString

The User’s last name.

users[x].membershipsArray

The list of memberships for the User.

users[x].memberships[x].dataObject

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

users[x].memberships[x].groupIdUUIDrequired

The Id of the Group of this membership.

users[x].memberships[x].idUUIDDefaults to secure random UUID

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

users[x].middleNameString

The User’s middle name.

users[x].mobilePhoneString

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

users[x].passwordStringrequired

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.

The value of password should contain only the password hash, or, if the encryptionScheme is omitted, the plain text password. Unless you are using a custom plugin that does not utilize base64, password should be base64 encoded. It is recommended to use a base64 encoded string, but if you are importing hashes from a legacy system that uses base16, base32, or another encoding and are writing a custom plugin, import the hash in the same format the plugin produces.

Please see the Password Hashes section for more information about importing particular password hashes.

users[x].passwordChangeReasonStringDefaults to Administrative

When passwordChangeRequired is set to true you may optionally set a reason for this change. The possible values are:

Administrative - the password must be changed due to an administrative action
Breached - the password must be changed due to it being identified as breached in some fashion
Expired - the password must be changed due to expiration
Validation - the password must be changed due to the password no longer meeting the configured minimum requirements

In practice, leaving the default makes the most sense. The other reasons are used by FusionAuth during runtime to automatically require a user to change their password.

users[x].passwordChangeRequiredBooleanDefaults to false

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

users[x].passwordLastUpdateInstantLongDefaults 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].preferredLanguagesArray<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].registrationsArray

The list of registrations for the User.

users[x].registrations[x].applicationIdUUIDrequired

The Id of the Application that this registration is for.

users[x].registrations[x].cleanSpeakIdUUID

users[x].registrations[x].dataObject

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

users[x].registrations[x].idUUIDDefaults to secure random UUID

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

users[x].registrations[x].insertInstantLongDefaults to now

The instant that this registration was created.

users[x].registrations[x].lastLoginInstantLong

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

users[x].registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

users[x].registrations[x].usernameString

The username of the User for this registration only.

users[x].registrations[x].usernameStatusStringDefaults 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].verifiedBooleanDefaults to false

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

users[x].registrations[x].verifiedInstantLongDefaults to now

The instant this registration was verified. This value will be ignored if verified is false.

users[x].saltString

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

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

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

users[x].twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this must be HmacSHA1 if provided. Any other value will be ignored.

users[x].twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this must be 6 if provided. Any other value will be ignored.

users[x].twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this must be 30 if provided. Any other value will be ignored.

users[x].twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

users[x].twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

users[x].twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

users[x].twoFactor.methods[x].secretString

A base64 encoded secret.

This field is required when method is authenticator.

users[x].twoFactor.recoveryCodesArray<String>

A list of recovery codes. These may be used in place of a code provided by an MFA factor. They are single use.

If a recovery code is used in a disable request, all MFA methods are removed. If, after that, a Multi-Factor method is added, a new set of recovery codes will be generated.

users[x].twoFactorDeliveryStringDefaults to NoneDEPRECATED

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.

Removed in 1.26.0

users[x].twoFactorEnabledBooleanDefaults 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.

Removed in 1.26.0

users[x].twoFactorSecretStringDEPRECATED

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.

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

Removed in 1.26.0

users[x].usernameString

The username of the User.

users[x].usernameStatusStringDefaults 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].verifiedBooleanDefaults to false

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

users[x].verifiedInstantLongDefaults to now

The instant this user’s email address was verified. This value will be ignored if verified is false.

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

Example Request JSON

{
  "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",
      "twoFactor": {
        "methods": [
          {
            "authenticator": {
              "algorithm": "HmacSHA1",
              "codeLength": 6,
              "timeStep": 30
            },
            "secret": "aGVsbG8Kd29ybGQKaGVsbG8gaGVsbG8=",
            "method": "authenticator"
          },
          {
            "method": "sms",
            "mobilePhone": "555-555-5555"
          },
          {
            "method": "email",
            "email": "example@fusionauth.io"
          }
        ]
      },
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true
    }
  ]
}

Response

Only a status code is available on the Import API, no JSON body will be returned.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Password Hashes

Password hashes can be imported into FusionAuth. This allows users to transparently use their old passwords while at no time exposing the plaintext password. This section contains details about importing specific password hashes.

You can also learn more about hashes in the password hashing reference, and you can implement your own custom hash as well.

Encoding

The standard FusionAuth password hashing schemes require the password hash to be a base64 encoded string. If your password hashes are encoded in a different format, they will need to either be converted and imported as base64, or you can create a custom plugin using an alternative encoding. You can see an example of converting below.

It is recommended to use a base64 encoded string, but if importing hashes from a legacy system that uses base16, base32, or another encoding, import the hash in the same format the plugin produces.

Example of Converting a Base16 Password Hash Value to Base64

hash_in_hex = "25d55ad283aa400af464c76d713c07ad"

def hex_to_base64_digest(hexdigest)
  [[hexdigest].pack("H*")].pack("m0")
end

puts hex_to_base64_digest(hash_in_hex)

Bcrypt

When importing a bcrypt hash, you may have a value such as:

$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

This single string represents the bcrypt version, factor, salt and hash.

The number before the final $ is the factor, the 22 characters after the final $ is the salt and the last 31 characters are the hash.

For the above bcrypt hash, 10 is the factor and should be placed in the factor field. N9qo8uLOickgx2ZMRZoMye is the salt and should be placed in the salt field. IjZAgcfl7p92ldGxad68LJZdL17lhWy is the hash value and should be placed in the password field.

MD5

When importing an MD5 password hash, you may not have a salt. If this is the case, use the empty string, '', as the salt. You may still use the salted MD5 plugin provided by FusionAuth.

MD5 is commonly stored in hexadecimal format, such as 25d55ad283aa400af464c76d713c07ad. The FusionAuth Import Users API requires imported password hashes to be base64 encoded. Convert any hexadecimal values to base64 before importing, or the import will not work.

Here is an example ruby script to convert hexadecimal values to base64 encoded:

Convert a Hexadecimal Password Hash Value to Base64

hash_in_hex = "25d55ad283aa400af464c76d713c07ad"

def hex_to_base64_digest(hexdigest)
  [[hexdigest].pack("H*")].pack("m0")
end

puts hex_to_base64_digest(hash_in_hex)

Import Refresh Tokens

Available Since Version 1.19.0

This API is used to import refresh tokens from an external system, this would generally be done during an initial user import or as an auxiliary step during a migration strategy.

Before using this API, create the Users, Applications and User Registrations. A validation error will be returned if the user does not exist, or is not registered for the application.

Request

Import Refresh Tokens

POST /api/user/refresh-token/import

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

refreshTokensArrayrequired

The list of refresh tokens to import.

refreshTokens[x].applicationIdUUIDrequired

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

refreshTokens[x].metaData.device.descriptionString

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

refreshTokens[x].metaData.device.lastAccessedAddressString

The IP address of this login request.

refreshTokens[x].metaData.device.lastAccessedInstantLong

The instant of this login request.

refreshTokens[x].metaData.device.nameString

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

refreshTokens[x].metaData.device.typeString

The type of device represented by the device parameter.

Prior to version 1.46.0, this value was restricted to the following types:

BROWSER
DESKTOP
LAPTOP
MOBILE
OTHER
SERVER
TABLET
TV
UNKNOWN

In version 1.46.0 and beyond, this value can be any string value you’d like, have fun with it!

refreshTokens[x].startInstantStringrequired

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

refreshTokens[x].tokenStringrequired

The string representation of the refresh token.

Prior to version 1.33.0, this value was limited to a maximum length of 191 characters. If you need to import a token that is longer than 191 characters, ensure you have upgraded to version 1.33.0 or later.

refreshTokens[x].userIdUUIDrequired

The unique user Id of the refresh token owner.

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

Example Request JSON

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

Response

The response does not contain a body, the HTTP status code will indicate the result of the request.

Response Codes

Code	Description
200	The request was successful.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Search for Users

This API is used to search for Users. This API may be called using the GET or POST HTTP methods, examples of each are provided below. The POST method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET or POST HTTP method will provide the same search results given the same query parameters.

Request

Which search query parameters are available and how they behave depends on the search engine type. Read more about the different types of search engines.

Database Search Engine

This is a good choice for smaller installs, embedded scenarios, or other places where the additional capability of Elasticsearch is not required.

Available Since Version 1.16.0

Search for Users by Id

GET /api/user/search?ids={uuid}&ids={uuid}

Search for Users by a query string

GET /api/user/search?queryString={queryString}

Search for Users by a query string and sort the response

GET /api/user/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

Request Parameters

accurateTotalBooleanDefaults to falseAvailable since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 users. This means that even if your query may match more than 10,000 users, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

expandArray<String>Defaults to [memberships, registrations]Available since 1.48.0

This parameter allows you to optionally remove the memberships and registrations from the API response. Removing these fields from the response may improve performance on large search requests, specifically when you are managing application roles through User Registrations and Group Memberships.

For backwards compatibility, the default behavior will be to return both memberships and registrations.

To request only the registrations but omit the memberships from the response, provide a value of [registrations]. To omit both the memberships and registrations from the response, provide a value of [].

idsUUID

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.

numberOfResultsIntegerDefaults to 25

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

queryStringString

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.

startRowIntegerDefaults to 0

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

sortFieldsArray

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

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].orderStringDefaults to asc

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

asc
desc

Request Headers

X-FusionAuth-TenantIdString

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

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

Search for Users using a JSON request body. This allows for larger requests than are possible using request parameters.

POST /api/user/search

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

expandArray<String>Defaults to [memberships, registrations]Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

search.accurateTotalBooleanDefaults to falseAvailable since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

search.idsArray<UUID>

A list of User Ids to retrieve. When using this parameter, the results are not paginated or sorted using the sortFields .

The search.ids and queryString parameters are mutually exclusive, they are listed here in order of precedence.

search.numberOfResultsIntegerDefaults to 25

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

search.queryStringString

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

search.startRowIntegerDefaults to 0

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

search.sortFieldsArray

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

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].orderStringDefaults to asc

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

asc
desc

Request Body Examples

Example Request JSON searching by ids

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

Example Request JSON searching by queryString for users with an email address

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

Example Request JSON searching by queryString for users with a firstName, lastName, fullName, email or username containing piper.

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

Example Request JSON to retrieve the first 50 users, ordered by email address, ascending.

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

Elasticsearch Search Engine

The Elasticsearch engine has advanced querying capabilities and better performance. You can also review the Elasticsearch search guide for more examples.

Search for Users by Id

GET /api/user/search?ids={uuid}&ids={uuid}

Search for Users by a query string

GET /api/user/search?queryString={queryString}

Search for Users by a query string and sort the response

GET /api/user/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

Search for Users by a raw JSON query

GET /api/user/search?query={query}

Search for Users with a nextResults token

GET /api/user/search?nextResults={nextResults}

Request Parameters

accurateTotalBooleanDefaults to falseAvailable since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

expandArray<String>Defaults to [memberships, registrations]Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

idsUUID

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.

nextResultsStringAvailable since 1.48.0

The encoded token returned in the nextResults field of a previous search response. Providing this token will return a result set for the page following the last result from the previous search response.

This parameter can be used to successfully page past the max_result_window limitation.

This parameter cannot be used with the ids , query , queryString , or sortFields parameters. The startRow parameter must be 0 or omitted.

See Extended Pagination for more information.

numberOfResultsIntegerDefaults to 25

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

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

queryStringString

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. Here are [the available fields for matching](/docs/reference/user-fields).

startRowIntegerDefaults to 0

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

sortFieldsArray

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].missingStringDefaults 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].nameString

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].orderStringDefaults to asc

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

asc
desc

Request Headers

X-FusionAuth-TenantIdString

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

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

Search for Users using a JSON request body. This allows for larger requests than are possible using request parameters.

POST /api/user/search

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

expandArray<String>Defaults to [memberships, registrations]Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

search.accurateTotalBooleanDefaults to falseAvailable since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

search.idsArray<UUID>

A list of User Ids to retrieve. When using this parameter, the results are not paginated or sorted using the sortFields .

The search.ids , query , and queryString parameters are mutually exclusive, they are listed here in order of precedence.

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

search.nextResultsStringAvailable since 1.48.0

This parameter can be used to successfully page past the max_result_window limitation.

This parameter cannot be used with the ids , query , queryString , or sortFields parameters. The startRow parameter must be 0 or omitted.

See Extended Pagination for more information.

search.numberOfResultsIntegerDefaults to 25

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

search.queryStringAvailable 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.queryStringString

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.

search.startRowIntegerDefaults to 0

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

search.sortFieldsArray

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].missingStringDefaults 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].nameString

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].orderStringDefaults to asc

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

asc
desc

Request Body Examples

Search Using Ids

Example Request JSON searching by ids

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

Search Using A Query String

Example Request JSON searching by queryString for users with an email address matching a pattern

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

Example Request JSON searching by queryString for users belonging to a specific group

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

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

Example Request JSON searching by queryString for active users with a certain email address without MFA enabled

{
  "search": {
    "numberOfResults": 25,
    "queryString": "email:/.*example.com/ AND active:true AND !(_exists_:twoFactor)",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Search Using A Query

Searches using query have two parts. You must build the JSON query parameter, then escape it and include it in a request.

A request includes not only a query, but also additional search parameters, such as sorting or pagination. For more, see the Searching Users With Elasticsearch guide.

Unverified Registrations

To search for users with unverified Registrations for a specific Application, you’d use this JSON for the query:

Query JSON

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

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "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
  }
}

Specific Role

To search for users with a Role in an Application, you’d use this JSON for the query:

Query JSON

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

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "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
  }
}

Specific Email Address

To search for users with a certain email address, you’d use this JSON for the query:

Query JSON

{
  "match": {
    "email": {
      "query": "dinesh@fusionauth.io"
    }
  }
}

And then escape and include it in this request JSON:

Request JSON

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

Boolean User Data Attribute

To search for users with custom user data attribute of dataMigrated with a value equal to true, you’d use this JSON for the query:

Query JSON

{
  "match": {
    "data.userMigrated": {
      "query": "true"
    }
  }
}

And then escape and include it in this request JSON:

Request JSON

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

Additional Query Examples

Below are additional query examples. The request JSON, in which the query must be escaped and included, is omitted.

Example JSON for the query parameter to search for users with a price range in their registration data

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

Example JSON for the query parameter to search for users with any value for userMigrated

{
  "constant_score": {
    "filter": {
      "exists": {
        "field": "data.userMigrated"
      }
    }
  }
}

Example Request JSON searching by nextResults for users using a token returned in a previous search response

{
  "search": {
    "numberOfResults": 25,
    "nextResults": "eyJscyI6WyIxLjAwMTQ2MTkiLG51bGwsInRlc3R1c2VyOTkwOUBsb2NhbC5jb20iLCJjNmI4ZjQyNC0wOTRjLTQ1MWYtYWMxNS05Y2ZkODI3NTZlNGEiXSwicXMiOiIqIiwic2YiOltdfQ"
  }
}

Response

The response contains the User objects that were found as part of the lookup or search. Both the database and Elasticsearch search engines return the response in the same format.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

expandableArray<String>Available since 1.48.0

The available expandable properties that are not expanded in the response.

For example, if you set the expand request parameter to [registrations] then the value of this parameter in the response will be [memberships] indicating that the memberships property was not expanded.

nextResultsStringAvailable since 1.48.0

A token that can be used in subsequent search requests to page forward after the last result of the current response.

This value will not be returned when FusionAuth is configured to use the database search engine.

See Extended Pagination for more information.

totalLong

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.

This value may cap out at 10,000 even if more users are found based upon the provided search query. Use the accurateTotal request parameter if you require this value to represent the actual number of matching users in the search index when your query may match more than 10,000 users.

usersArray

The list of Users.

users[x].activeBoolean

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

users[x].breachedPasswordLastCheckedInstantLong

The instant this user’s password was last checked to determine if is compromised.

users[x].birthDateString

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

users[x].cleanSpeakIdUUID

users[x].connectorIdUUIDAvailable since 1.18.0

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

users[x].dataObject

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

users[x].emailString

The User’s email address.

users[x].encryptionSchemeStringAvailable 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].expiryLong

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

users[x].firstNameString

The first name of the User.

users[x].fullNameString

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

users[x].idUUID

The User’s unique Id.

users[x].imageUrlString

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

users[x].insertInstantLong

The instant when the User was created.

users[x].lastLoginInstantLong

The instant when the User logged in last.

users[x].lastNameString

The User’s last name.

users[x].lastUpdateInstantLong

The last instant when the User was updated. Note: webhooks may be another effective way to track user changes.

users[x].membershipsArray

The list of memberships for the User.

users[x].memberships[x].dataObject

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

users[x].memberships[x].groupIdUUID

The Id of the Group of this membership.

users[x].memberships[x].idUUID

The unique Id of this membership.

users[x].memberships[x].insertInstantLong

The instant that the membership was created.

users[x].middleNameString

The User’s middle name.

users[x].mobilePhoneString

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

users[x].passwordChangeRequiredBoolean

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

users[x].passwordLastUpdateInstantLong

The instant that the User last changed their password.

users[x].preferredLanguagesArray<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].registrationsArray

The list of registrations for the User.

users[x].registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

users[x].registrations[x].authenticationTokenString

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

users[x].registrations[x].cleanSpeakIdUUID

users[x].registrations[x].dataObject

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

users[x].registrations[x].idUUID

The Id of this registration.

users[x].registrations[x].insertInstantLong

The instant that this registration was created.

users[x].registrations[x].lastLoginInstantLong

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

users[x].registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

users[x].registrations[x].timezoneString

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

users[x].registrations[x].tokensMap<String,String>DEPRECATED

A map that contains tokens returned from identity providers.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

users[x].registrations[x].usernameString

The username of the User for this registration only. This is for display purposes and cannot be used to login.

users[x].registrations[x].usernameStatusString

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

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

user[x].registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

users[x].tenantIdUUID

The Id of the Tenant that this User belongs to.

users[x].timezoneString

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].twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

users[x].twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

users[x].twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

users[x].twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

users[x].twoFactor.methods[x].idString

The unique Id of the method.

users[x].twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

users[x].twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

users[x].twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

users[x].twoFactorDeliveryStringDEPRECATED

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

The possible values are:

None
TextMessage

Removed in 1.26.0

users[x].twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0

users[x].usernameString

The username of the User.

users[x].usernameStatusString

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

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

user[x].verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Example Search Results Response JSON

{
  "expandable": [],
  "nextResults": "eyJscyI6WyIxLjAwMTQ2MTkiLG51bGwsInRlc3R1c2VyOTkwOUBsb2NhbC5jb20iLCJjNmI4ZjQyNC0wOTRjLTQ1MWYtYWMxNS05Y2ZkODI3NTZlNGEiXSwicXMiOiIqIiwic2YiOltdfQ",
  "total": 1,
  "users": [
    {
      "active": true,
      "birthDate": "1976-05-30",
      "breachedPasswordLastCheckedInstant": 1471786483322,
      "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"
          ],
          "username": "johnny123",
          "usernameStatus": "ACTIVE",
          "verified": true,
          "verifiedInstant": 1698772159415
        }
      ],
      "timezone": "America/Denver",
      "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
      "twoFactor": {
        "methods": [
          {
            "authenticator": {
              "algorithm": "HmacSHA1",
              "codeLength": 6,
              "timeStep": 30
            },
            "id": "35VW",
            "method": "authenticator"
          },
          {
            "id": "V7SH",
            "method": "sms",
            "mobilePhone": "555-555-5555"
          },
          {
            "email": "example@fusionauth.io",
            "id": "7K2G",
            "method": "email"
          }
        ]
      },
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true,
      "verifiedInstant": 1698772159415
    }
  ]
}

Flush the Search Engine

This API is used to issue a flush request to the FusionAuth Search. This will cause any cached data to be written to disk. In practice it is unlikely you’ll find a need for this API in production unless you are performing search requests immediately following an operation that modifies the index and expecting to see the results immediately.

Request

Flushes the Search Engine

PUT /api/user/search

Response

The response does not contain a body. It only contains one of the status codes below.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Retrieve Recent Logins

Available Since Version 1.4.0

This API is used to retrieve recent logins.

Request

Retrieve recent logins

GET /api/user/recent-login?limit={limit}&offset={offset}&userId={userId}

Request Parameters

limitIntegerDefaults to 10

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

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

userIdUUID

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.

Request Headers

X-FusionAuth-TenantIdString

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

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

Response

The response will contain recent logins containing no more than the value set by the limit parameter. By design, this API does not return the total number of results and only lets paginate through the results from newest to oldest.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

loginsArray

A list of recent logins.

logins[x].applicationIdUUID

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

logins[x].applicationNameString

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

logins[x].instantLong

The instant this login occurred.

logins[x].ipAddressString

The IP address if provided during the login request.

logins[x].location.cityStringAvailable since 1.30.0

The city where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].location.countryStringAvailable since 1.30.0

The country where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].location.latitudeDoubleAvailable since 1.30.0

The latitude where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].location.longitudeDoubleAvailable since 1.30.0

The longitude where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].location.regionStringAvailable since 1.30.0

The geographic location where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].location.zipcodeStringAvailable since 1.30.0

The zipcode where the login request originated.

Note: An Enterprise plan is required to utilize login location.

logins[x].loginIdString

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

logins[x].userIdUUID

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

Example Response JSON

{
  "logins": [
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "applicationName": "PiedPiper",
      "instant": 1549493410058,
      "ipAddress": "42.42.42.42",
      "location": {
        "city": "Seattle",
        "country": "US",
        "latitude": 47.60621,
        "longitude": -122.33207,
        "region": "WA"
      },
      "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",
      "location": {
        "city": "Denver",
        "country": "US",
        "latitude": 39.73913,
        "longitude": -104.9845,
        "region": "CO"
      },
      "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",
      "location": {
        "city": "Dhaka",
        "country": "BD",
        "latitude": 23.7104,
        "longitude": 90.40744,
        "region": "81"
      },
      "loginId": "bob@gmail.com",
      "userId": "6a802b03-17e3-404f-830f-ea5c30ca50df"
    }
  ]
}

Verify a User’s Email

This API is used to mark a User’s email as verified. This is usually called after the User receives the verification email after they register and they click the link in the email.

Request

Verifies the User's email address using the verificationId.

POST /api/user/verify-email

Verifies the User's email address using the verificationId.

POST /api/user/verify-email/{verificationId}

Request Parameters

verificationIdStringrequiredDEPRECATED

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

Deprecated since 1.28.0

This value can still be provided on the URL segment as shown in the above example, but it is recommended you send this value in the request body instead using the verificationId field. If the value is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

Request Body

oneTimeCodeStringAvailable since 1.27.0

The short code used to verify the User’s account is valid by ensuring they have access to the provided email address. This field is required when the email verification strategy on the Tenant is set to Form field.

verificationIdStringrequiredAvailable since 1.27.0

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.

When using the Form field strategy for Email verification, this value is used along with the oneTimeCode as a pair to verify the email address.

If the verificationId is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

Request Headers

X-FusionAuth-TenantIdString

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

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

Available since version 1.37.0

This API can be used to mark a user as verified without requiring the user to actually complete a verification process.

Administratively verify the User's email address.

POST /api/user/verify-email

Request Body

userIdStringrequired

The unique Id of the user to mark verified.

Response

The response does not contain a body. It only contains one of the status codes below.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to update doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Resend Verification Email

This API is used to resend the verification email to a User. This API is useful if the User has deleted the email, or the verification Id has expired. By default, the verification Id will expire after 24 hours. You can modify this duration in the Tenant settings.

Request

Resend the verification email

PUT /api/user/verify-email?applicationId={applicationId}&email={email}

Request Parameters

applicationIdStringAvailable since 1.21.0

The Id of the application. If valid, the email template configured in the Application settings will be used, if present. If not present, the email template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template.

emailStringrequired

The email address used to uniquely identify the User.

Request Headers

X-FusionAuth-TenantIdString

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

PUT /api/user/verify-email?applicationId={applicationId}&email={email}&sendVerifyEmail={sendVerifyEmail}

Request Parameters

applicationIdStringAvailable since 1.21.0

emailStringrequired

The email address used to uniquely identify the User.

sendVerifyEmailBooleanDefaults 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-TenantIdString

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

When authenticated using an API key a response body will be provided. If an API key was not used to authenticate the request no body is returned.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body if an API key was used for authentication. If no API key was provided no response body will be returned.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to update doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

verificationIdString

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.

verificationOneTimeCodeString

Depending on your tenant configuration, this may be returned. The verification One Time Code is used with the gated Email Verification workflow. The user enters this code to verify their email.

Note: A paid plan is required to utilize gated email.

Example Response JSON

{
  "verificationId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4",
  "verificationOneTimeCode": "JJ6RTS"
}

Start Forgot Password Workflow

This API is used to start the forgot password workflow for a single User.

For example, on your login form you may have a button for Forgot your password. This would be the API you would call to initiate the request for the user. If the email configuration is complete, the user will be sent the forgot password email containing a link containing the changePasswordId. The provided link should take the user to a form that allows them to change their password. This form should contain a hidden field for the changePasswordId generated by this API.

By default the changePasswordId is valid to be used with the Change Password API for 10 minutes. If a 404 is returned when using this Id to change the password, the workflow will need to be started again to generate a new identifier. This duration can be modified using the Tenant API or in the FusionAuth UI.

You may optionally authenticate this request with an API key to allow for some additional request parameters and the generated changePasswordId will be returned in the JSON body. This may be helpful if you wish to use your own email system or you have an alternative method to call the Change Password API.

If FusionAuth sends an email to the user, it will either use the email top level property on the user or it will use a custom data attribute named email as well (i.e. data.email). This allows you to have a user that has no email address for login or allow distinct users to share email addresses.

Request

Start the forgot password workflow without an API Key.

POST /api/user/forgot-password

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUIDAvailable since 1.21.0

loginIdStringrequired

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

stateObject

An optional object that will be returned un-modified when you complete the forgot password request using the Change a User’s Password API. This may be useful to return the user to particular state once they complete the password change.

Example Request JSON

{
  "applicationId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
  "loginId": "example@fusionauth.io"
}

Start the forgot password workflow using an API key

POST /api/user/forgot-password

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUIDAvailable since 1.21.0

changePasswordIdString

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.

loginIdStringrequired

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

sendForgotPasswordEmailBooleanDefaults to true

Whether or not calling this API should attempt to send the user an email using the configured Forgot Password email template. Setting this to false will begin the Forgot Password workflow without sending an email and only create the changePasswordId, this may be useful if you want to send an email outside of FusionAuth, or complete this workflow without the use of email.

When setting this to false you will not be required to have configured the Forgot Password email template in the FusionAuth tenant. Prior to 1.43.0, even when setting this to false, the Tenant would be required to have configured the Forgot Password email template.

stateObject

An optional object that will be returned un-modified when you complete the forgot password request. This may be useful to return the user to particular state once they complete the password change.

Example Request JSON

{
  "applicationId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4",
  "loginId": "example@fusionauth.io",
  "sendForgotPasswordEmail": false,
  "state": {
    "lastPage": "/foo/baz"
  }
}

Response

Response Codes

Code	Description
200	The request was successful. A JSON response body will be provided when authenticated using an API key, when the API key has been omitted from the request, no response body is provided.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
403	The forgot password functionality has been disabled. This is caused by an administrator setting the Forgot Password Email Template to the option Feature Disabled. No template selected. in the Tenant Email configuration. See Tenants -> Email -> Template settings in the FusionAuth admin UI.
404	The User could not be found.
422	The User does not have an email address, this request cannot be completed. Before attempting the request again add an email address to the user.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

changePasswordIdString

The change password Id that was generated by this API request. This identifier may be used by the Change a User’s 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.

Example Response JSON

{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

Change a User’s Password

This API is used to change the User’s password.

This API may be used as the second part of the Forgot Password workflow. For example, after the User is sent an email that contains a link to a web form that allows them to update their password you will call this API with the changePasswordId and their updated password. If the changePasswordId is valid then the User’s password will be updated.

This API may also be used separately from the Forgot Password workflow by omitting the changePasswordId and using the loginId instead.

By default the changePasswordId is valid for 10 minutes after it was generated. If a 404 is returned when using the change password Id, the workflow will need to be started again to generate a new identifier. This duration can be modified using the Tenant API or in the admin UI.

When this API successfully completes, all refresh tokens and outstanding Change Password Ids (i.e. changePasswordId) currently assigned to the user will be expired or revoked. This means that if a user is using a refresh token they will be forced to re-authenticate with their new password.

Request

This usage is generally intended to be part of an email workflow and does not require authentication. The changePasswordId used on this API request will have been previously generated by the Start Forgot Password API or by using the Forgot Password workflow on the FusionAuth login page.

Change a User’s password using the change password Id

POST /api/user/change-password

Change a User’s password using the change password Id

POST /api/user/change-password/{changePasswordId}

Request Parameters

changePasswordIdStringrequiredDEPRECATED

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 and the Tenant configuration has enabled implicit email verification.

Deprecated since 1.33.0

This value can still be provided on the URL segment as shown in the above example, but it is recommended you send this value in the request body instead using the changePasswordId field. If the value is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

changePasswordIdStringrequiredAvailable since 1.33.0

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

If the changePasswordId is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

currentPasswordString

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

passwordStringrequired

The User’s new password.

trustChallengeStringAvailable since 1.33.0

This field is marked optional because it is only required when the user has enabled two-factor authentication, and a trustChallenge was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a trustChallenge was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API.

trustTokenStringAvailable since 1.33.0

This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the changePasswordId.

Example JSON Request

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

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

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

POST /api/user/change-password

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUIDAvailable since 1.30.0

If not provided, only the tenant configuration will be used when resolving email templates.

currentPasswordString

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

loginIdStringrequired

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.

passwordStringrequired

The User’s new password.

trustChallengeStringAvailable since 1.33.0

trustTokenStringAvailable since 1.33.0

Example JSON Request

{
  "applicationId": "18cec3c9-003b-433f-8412-6e31afca5bcf",
  "currentPassword": "too many secrets",
  "loginId": "cosmo@playtronics.com",
  "password": "Setec Astronomy"
}

Available Since Version 1.5.0

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.

Change a User's password using a JWT

POST /api/user/change-password

Request Headers

X-FusionAuth-TenantIdString

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

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

Request Body

currentPasswordStringrequired

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

passwordStringrequired

The User’s new password.

refreshTokenString

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.

trustChallengeStringAvailable since 1.33.0

trustTokenStringAvailable since 1.33.0

Example JSON Request

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

Response

Response Codes

Code	Description
200	The request was successful. Starting in version `1.5.0` a JSON response body will be returned unless the API was called with an API key was used with a `loginId`. Prior to version `1.5.0` a JSON body was not returned.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. Beginning in version `1.33.0` a status code of `400` may also be used to indicate additional trust is required to complete this request. In this case the following error will be returned. Example Response JSON `{ "generalErrors": [ { "code": "[TrustTokenRequired]", "message": "This request requires a Trust Token. Use the Start Two-Factor API to obtain a Trust Token required to complete this request." } ] }` To complete this request you must obtain a `trustToken`. To obtain a `trustToken` complete a Two-Factor Login request. Beginning in version `1.43.0` a status code of `400` may also indicate that the supplied `currentPassword` or `loginId` were incorrect if the call was made with an API key. For security reasons without an API key this will return a `404`.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The User could not be found using the `changePasswordId` or `loginId` value from the request. If using the `changePasswordId` the id is either incorrect or expired. Another reason for this status code is that you have provided the `currentPassword` parameter and it does not match the current password.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body

This JSON response body will only be returned when using a changePasswordId parameter or a JWT to change the password.

When calling this API with an API key no response body will be returned.

oneTimePasswordStringAvailable since 1.5.0

A one time password that can be used as a substitute for your loginId and password on the Login API.

stateObjectAvailable since 1.5.0

An optional object that is returned un-modified when the forgot password request is completed. This may be useful to return the user to particular state once they complete the password change.

Example Response JSON

{
  "oneTimePassword": "YQNfvoDJy4_0As9iLTk9hpjF5z_C3VWVyBy95vFZr0M"
}