User APIs

1. Overview

This page contains all of the APIs for managing users.

2. Create a User

This API is used to create a new User.

2.1. Request

Create a User with a randomly generated Id

URI

POST /api/user

Create a User with the provided unique Id

URI

POST /api/user/{userId}

Table 1. Request Parameters

userId [UUID] Optional defaults to secure random UUID

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

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

Table 2. Request Body

sendSetPasswordEmail [Boolean] Optional defaults to false

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

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

skipVerification [Boolean] Optional defaults to false

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

user.birthDate [String] Optional

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

user.data [Object] Optional

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

user.email [String] Optional

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

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

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

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

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

user.expiry [Long] Optional

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

user.factor [String] Optional

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

user.firstName [String] Optional

The first name of the User.

user.fullName [String] Optional

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

user.imageUrl [String] Optional

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

user.lastName [String] Optional

The User’s last name.

user.middleName [String] Optional

The User’s middle name.

user.mobilePhone [String] Optional

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

user.password [String] Optional

The User’s password.

user.passwordChangeRequired [Boolean] Optional

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

user.preferredLanguages [Array<String>] Optional

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

user.timezone [String] Optional

The User’s preferred timezone. The format is not enforced, however it is recommended to use a timezone in the TZ format such as

America/Denver or US/Mountain

users.twoFactorDelivery [String] Optional defaults to None

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

The possible values are:

  • None

  • TextMessage

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

user.twoFactorEnabled [Boolean] Optional

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

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

user.twoFactorSecret [String] Optional

The secret used to generate Two Factor verification codes.

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

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

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

user.username [String] Optional

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

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

user.usernameStatus [String] Optional

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

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

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

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

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.

Table 4. Response Body

user.active [Boolean]

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

user.birthDate [String]

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

user.cleanSpeakId [UUID]

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

user.data [Object]

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

user.email [String]

The User’s email address.

user.expiry [Long]

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

user.firstName [String]

The first name of the User.

user.fullName [String]

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

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

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

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

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

user.passwordChangeRequired [Boolean]

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

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

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

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].cleanSpeakId [UUID]

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

user.registrations[x].data [Object]

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

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

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

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

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

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

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

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration.

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

A map that contains tokens returned from identity providers.

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

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.timezone [String]

The User’s preferred timezone.

users.twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

user.twoFactorEnabled [Boolean]

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

user.username [String]

The username of the User.

user.usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.verified [Boolean]

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

Example Response JSON
{
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

3. Retrieve a User

This API is used to retrieve the information about a single User. You can use the User’s Id, username or email address to retrieve the User. The Id is specified on the URI and the username or email are specified as URL parameters.

3.1. Request

Retrieve a User by Id

URI

GET /api/user/{userId}

Table 5. Request Parameters

userId [UUID] Required

The unique Id of the User to retrieve.

Retrieve a User by login Id

URI

GET /api/user?loginId={loginId}

Table 6. Request Parameters

loginId [String] Required

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

Retrieve a User by email

URI

GET /api/user?email={email}

Table 7. Request Parameters

email [String] Required

The email of the User to retrieve.

Retrieve a User by username

URI

GET /api/user?username={username}

Table 8. Request Parameters

username [String] Required

The username of the User to retrieve.

Retrieve a User by Change Password Id

URI

GET /api/user?changePasswordId={changePasswordId}

Table 9. Request Parameters

changePasswordId [String] Required

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

Retrieve a User by Email Verification Id

URI

GET /api/user?verificationId={verificationId}

Table 10. Request Parameters

verificationId [String] Required

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

Retrieve a User using a JWT

URI

GET /api/user

3.2. Response

The response for this API contains the User.

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

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.

Table 12. Response Body

user.active [Boolean]

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

user.birthDate [String]

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

user.cleanSpeakId [UUID]

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

user.data [Object]

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

user.email [String]

The User’s email address.

user.expiry [Long]

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

user.firstName [String]

The first name of the User.

user.fullName [String]

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

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

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

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

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

user.passwordChangeRequired [Boolean]

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

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

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

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].cleanSpeakId [UUID]

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

user.registrations[x].data [Object]

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

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

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

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

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

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

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

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration.

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

A map that contains tokens returned from identity providers.

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

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.timezone [String]

The User’s preferred timezone.

users.twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

user.twoFactorEnabled [Boolean]

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

user.username [String]

The username of the User.

user.usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.verified [Boolean]

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

Example Response JSON
{
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

4. Update a User

This API is used to update an existing User. You must specify the Id of the User you are updating on the URI. You must specify all of the properties of the User when calling this API. This API doesn’t merge the existing User and your new data. It replaces the existing User with your new data.

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.

4.1. Request

Update the User with the given Id

URI

PUT /api/user/{userId}

Table 13. Request Parameters

userId [UUID] Required

The Id of the User to update.

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.

Table 14. Request Body

skipVerification [Boolean] Optional defaults to false

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

user.birthDate [String] Optional

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

user.data [Object] Optional

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

user.email [String] Optional

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

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

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

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

This field is ignored unless the password field is also provided.

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

user.expiry [Long] Optional

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

user.factor [String] Optional

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

user.firstName [String] Optional

The first name of the User.

user.fullName [String] Optional

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

user.imageUrl [String] Optional

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

user.lastName [String] Optional

The User’s last name.

user.middleName [String] Optional

The User’s middle name.

user.mobilePhone [String] Optional

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

user.password [String] Optional

The User’s password.

user.passwordChangeRequired [Boolean] Optional

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

user.preferredLanguages [Array<String>] Optional

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

user.timezone [String] Optional

The User’s preferred timezone. The format is not enforced, however it is recommended to use a timezone in the TZ format such as

America/Denver or US/Mountain

users.twoFactorDelivery [String] Optional defaults to None

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

The possible values are:

  • None

  • TextMessage

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

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

user.twoFactorEnabled [Boolean] Optional

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

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

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

user.twoFactorSecret [String] Optional

The secret used to generate Two Factor verification codes.

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

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

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

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

user.username [String] Optional

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

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

user.usernameStatus [String] Optional

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

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

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

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

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

Table 16. Response Body

user.active [Boolean]

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

user.birthDate [String]

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

user.cleanSpeakId [UUID]

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

user.data [Object]

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

user.email [String]

The User’s email address.

user.expiry [Long]

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

user.firstName [String]

The first name of the User.

user.fullName [String]

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

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

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

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

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

user.passwordChangeRequired [Boolean]

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

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

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

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].cleanSpeakId [UUID]

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

user.registrations[x].data [Object]

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

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

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

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

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

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

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

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration.

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

A map that contains tokens returned from identity providers.

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

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.timezone [String]

The User’s preferred timezone.

users.twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

user.twoFactorEnabled [Boolean]

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

user.username [String]

The username of the User.

user.usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.verified [Boolean]

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

Example Response JSON
{
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

5. 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. Soft deleted Users are marked as inactive but not deleted from FusionAuth.

5.1. Request

Deactivate a User (Soft Delete)

URI

DELETE /api/user/{userId}

Permanently Delete a User

URI

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

Table 17. Request Parameters

userId [UUID] Required

The Id of the User to delete.

hardDelete [Boolean] Optional defaults to false

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

5.2. Response

This API does not return a JSON response body.

Table 18. Response Codes
Code Description

200

The request was successful. The response will be empty.

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.

404

The object you are trying to delete 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.

6. Bulk Delete Users

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

6.1. Request

Deactivate Users

URI

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

Permanently Delete Users

URI

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

Table 19. Request Parameters

userId [UUID] Required

The Id of the User to delete. Repeat this parameter for each user to be deleted.

hardDelete [Boolean] Optional defaults to false

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

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

URI

DELETE /api/user/bulk

Table 20. Request Body

hardDelete [Boolean] Optional defaults to false

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

userIds [Array] Required

An array of User Ids to delete.

Example Request JSON
{
  "hardDelete": false,
  "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"
  ]
}

6.2. Response

This API does not return a JSON response body.

Table 21. Response Codes
Code Description

200

The request was successful. The response will be empty.

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.

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.

7. Reactivate a User

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

7.1. Request

Reactivate the User

URI

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

Table 22. Request Parameters

userId [UUID] Required

The Id of the User to reactivate.

7.2. Response

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

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

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

Table 24. Response Body

user.active [Boolean]

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

user.birthDate [String]

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

user.cleanSpeakId [UUID]

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

user.data [Object]

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

user.email [String]

The User’s email address.

user.expiry [Long]

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

user.firstName [String]

The first name of the User.

user.fullName [String]

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

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

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

user.insertInstant [Long]

The instant when user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

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

user.passwordChangeRequired [Boolean]

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

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

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

user.registrations [Array]

The list of registrations for the User.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].cleanSpeakId [UUID]

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

user.registrations[x].data [Object]

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

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

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

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

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

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

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

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration.

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

A map that contains tokens returned from identity providers.

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

user.registrations[x].username [String]

The username of the User for this registration only.

user.registrations[x].usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.timezone [String]

The User’s preferred timezone.

users.twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

user.twoFactorEnabled [Boolean]

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

user.username [String]

The username of the User.

user.usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

user.verified [Boolean]

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

Example Response JSON
{
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

8. Import Users

This API is used to bulk import multiple Users into FusionAuth. Each User must have at least an email or a username. 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.

8.1. Request

Import Multiple Users

URI

POST /api/user/import

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.

Table 25. Request Body

encryptionScheme [String] Optional

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

The following encryptors are provided with FusionAuth:

factor [Integer] Optional

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

users [Array] Required

The list of Users to import.

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

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

users[x].birthDate [String] Optional

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

users[x].data [Object] Optional

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

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

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

users[x].email [String] Optional

The User’s email address.

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

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

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

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

The following encryptors are provided with FusionAuth:

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

users[x].expiry [Long] Optional

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

users[x].factor [String] Optional

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

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

users[x].firstName [String] Optional

The first name of the User.

users[x].fullName [String] Optional

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

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

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

users[x].imageUrl [String] Optional

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

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

The instant when user was created.

users[x].lastName [String] Optional

The User’s last name.

users[x].middleName [String] Optional

The User’s middle name.

users[x].mobilePhone [String] Optional

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

users[x].password [String] Optional

The User’s password. Required if encryptionScheme is provided.

users[x].passwordChangeRequired [Boolean] Optional

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

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

Indicates that last instant the password was changed.

If encryptionScheme is omitted this value will be ignored and set to the 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].registrations [Array] Optional

The list of registrations for the User.

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

The Id of the Application that this registration is for.

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

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

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

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

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

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

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

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

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

The instant that this registration was created.

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

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

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

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

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

The username of the User for this registration only.

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

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

users[x].salt [String] Optional

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

users[x].tenantId [UUID] Optional

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

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

users[x].timezone [String] Optional

The User’s preferred timezone. This can be used as a default to display instants. It is recommended that you allow users to change this on a per-session basis.

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

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

The possible values are:

  • None

  • TextMessage

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

users[x].twoFactorEnabled [Boolean] Optional

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

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

users[x].twoFactorSecret [String] Optional

The secret used to generate Two Factor verification codes.

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

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

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

users[x].username [String] Optional

The username of the User.

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

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

validateDbConstraints [Boolean] Optional defaults to false

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

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

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

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

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",
      "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"
        }
      ],
      "salt": "47bafdd3-b99d-4ffd-a5be-e414c80905f0",
      "timezone": "America/Denver",
      "twoFactorEnabled": false,
      "usernameStatus": "ACTIVE",
      "username": "johnny123"
    }
  ]
}

8.2. Response

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

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

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.

9. Search for Users

This API is used to search for Users.

9.1. Request

Search for Users by Id

URI

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

Search for Users by a query string

URI

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

Search for Users by a query string and sort the response

URI

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

Table 27. Request Parameters

ids [UUID] Optional

The list of User Ids to lookup. By specifying this URL parameter multiple times you can lookup multiple Users.

numberOfResults [Integer] Optional defaults to 20

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

queryString [String] Optional

The Elasticsearch query string that used to search for Users.

startRow [Integer] Optional defaults to 0

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

sortFields [Array] Optional

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

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

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

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

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

sortFields[x].name [String] Required

The name of the field to sort.

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

  • birthDate

  • email

  • fullName

  • insertInstant

  • login

  • username

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

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

  • asc

  • desc

9.2. Response

The response contains the User objects that were found as part of the lookup or search.

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

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.

Table 29. Response Body

users [Array]

The list of Users.

users[x].active [Boolean]

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

users[x].birthDate [String]

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

users[x].cleanSpeakId [UUID]

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

users[x].data [Object]

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

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

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

users[x].email [String]

The User’s email address.

users[x].expiry [Long]

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

users[x].firstName [String]

The first name of the User.

users[x].fullName [String]

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

users[x].id [UUID]

The User’s unique Id.

users[x].imageUrl [String]

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

users[x].lastLoginInstant [Long]

The instant when the User logged in last.

users[x].lastName [String]

The User’s last name.

users[x].middleName [String]

The User’s middle name.

users[x].mobilePhone [String]

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

users[x].passwordChangeRequired [Boolean]

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

users[x].passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

users[x].registrations [Array]

The list of registrations for the User.

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

The Id of the Application that this registration is for.

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

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

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

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

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

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

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

The Id of this registration.

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

The instant that this registration was created.

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

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

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

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

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

The username of the User for this registration only.

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

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

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

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

users[x].timezone [String]

The User’s preferred timezone. This can be used as a default to display instants. It is recommended that you allow User’s to change this per-session.

users[x].twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

users[x].twoFactorEnabled [Boolean]

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

users[x].username [String]

The username of the User.

users[x].usernameStatus [String]

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

  • ACTIVE - the username is active

  • PENDING - the username is pending approval/moderation

  • REJECTED - the username was rejected during moderation

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

users[x].verified [Boolean]

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

Example Response JSON
{
  "users": [
    {
      "active": true,
      "birthDate": "1976-05-30",
      "data": {
        "displayName": "Johnny Boy",
        "favoriteColors": [
          "Red",
          "Blue"
        ]
      },
      "email": "example@fusionauth.io",
      "expiry": 1571786483322,
      "firstName": "John",
      "fullName": "John Doe",
      "id": "00000000-0000-0001-0000-000000000000",
      "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
      "lastLoginInstant": 1471786483322,
      "lastName": "Doe",
      "middleName": "William",
      "mobilePhone": "303-555-1234",
      "passwordChangeRequired": false,
      "passwordLastUpdateInstant": 1471786483322,
      "preferredLanguages": [
        "en",
        "fr"
      ],
      "registrations": [
        {
          "applicationId": "10000000-0000-0002-0000-000000000001",
          "data": {
            "displayName": "Johnny",
            "favoriteSports": [
              "Football",
              "Basketball"
            ]
          },
          "id": "00000000-0000-0002-0000-000000000000",
          "insertInstant": 1446064706250,
          "lastLoginInstant": 1456064601291,
          "preferredLanguages": [
            "en",
            "fr"
          ],
          "roles": [
            "user",
            "community_helper"
          ],
          "tokens": {
            "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
            "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
          },
          "username": "johnny123",
          "usernameStatus": "ACTIVE"
        }
      ],
      "timezone": "America/Denver",
      "twoFactorEnabled": false,
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true
    }
  ]
}

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

10.1. Request

Verifies the User’s email address using the verificationId.

URI

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

Table 30. Request Parameters

verificationId [String] Required

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

10.2. Response

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

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

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

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

11.1. Request

Resend the verification email

URI

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

Table 32. Request Parameters

email [String] Required

The email address used to uniquely identify the User.

Resend the verification email using an API key

URI

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

Table 33. Request Parameters

email [String] Required

The email address used to uniquely identify the User.

sendVerifyEmail [Boolean] Optional defaults to true

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

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

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

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

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 verify email functionality has been disabled. FusionAuth is unable to send Email Verification emails.

404

The object you are trying to updated 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.

Table 35. Response Body

verificationId [String]

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

Example Response JSON
{
  "verificationId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

12. 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 System Configuration 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.

12.1. Request

Start the forgot password workflow without an API Key.

URI

POST /api/user/forgot-password

Table 36. Request Body

loginId [String] Required

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

Example Request JSON
{
  "loginId": "example@fusionauth.io"
}

Start the forgot password workflow using an API key

URI

POST /api/user/forgot-password

Table 37. Request Body

changePasswordId [String] Optional

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

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

loginId [String] Required

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

sendForgotPasswordEmail [Boolean] Optional defaults to true

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

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

12.2. Response

Table 38. 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 under SettingsSystem in FusionAuth.

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.

Table 39. Response Body

changePasswordId [String]

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

Example Response JSON
{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

13. 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 System Configuration API or in the FusionAuth 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.

13.1. Request

Changes a User’s password using the change password Id.

URI

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

Table 40. Request Parameters

changePasswordId [String] Required

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

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

Table 41. Request Body

currentPassword [String] Optional

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

password [String] Required

The User’s new password.

Changes a User’s password using a login Id or change password Id

URI

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

Table 42. Request Parameters

changePasswordId [String] Optional

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

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

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 the successful use of this identifier to change the User’s password will implicitly verify the User if not already verified.

Table 43. Request Body

currentPassword [String] Optional

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

loginId [String] Optional

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

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

password [String] Required

The User’s new password.

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

13.2. Response

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

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

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.

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.

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

14.1. Request

Flushes the Search Engine

URI

PUT /api/user/search

14.2. Response

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

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

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.