Update a User Registration

This API is used to update an existing User Registration.

You must specify the Id of the User Registration you are updating on the URI. You must specify the User Id and the Application Id on the URI to identify the registration that is being updated.

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

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

Request#

Update a User Registration

PUT/api/user/registration/{userId}/{applicationId}

PATCH/api/user/registration/{userId}/{applicationId}

For backward compatibility, the PATCH method accepts the same media type (specified by a Content-Type of application/json) and body as the PUT request. You can also use the following media types for different behavior:

JSON Patch/RFC 6902: application/json-patch+json
JSON Merge Patch/RFC 7396: merge-patch+json

For details, see the PATCH documentation.

Using a media type of application/json merges the provided request parameters into the existing object. As a result, all parameters are optional with PATCH: only provide the values you want to change. To remove a value, provide a null value. Patching an Array appends all values in the new list to the old list.

Request Parameters#

applicationIdUUIDrequiredAvailable since 1.25.0

The Id of the Application for which the User is registered.

While required, this parameter may be provided in the request body as well. If the applicationId is provided in both the URL and the request body, the value on the URL will take precedence. Prior to version 1.25.0 this value must be provided in the request body.

userIdUUIDrequiredImmutable

The Id of the User that is updating their User Registration for the Application.

Request Headers#

X-FusionAuth-TenantIdStringoptional

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

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. 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#

generateAuthenticationTokenBooleanoptionalDefaults to false

Determines if FusionAuth should generate an Authentication Token for this registration.

registration.applicationIdUUIDrequired

The Id of the Application that this registration is for.

Beginning in version 1.25.0 this value, while still required may be provided on the request as a URL segment. If the applicationId is provided on the URL, it will take precedence over the value found in the request body.

registration.authenticationTokenStringoptional

The authentication token that may be used in place of the User's password when authenticating against this application represented by this registration. This parameter is ignored if generateAuthenticationToken is set to true and instead the value will be generated.

registration.dataObjectoptional

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

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

The maximum number of allowed preferred languages is 20.

registration.rolesArray<String>optional

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.

registration.timezoneStringoptional

The User's preferred timezone for this Application registration. The string must be in an IANA time zone format.

registration.usernameStringoptional

The username of the User for this Application. This username cannot be used to login. It is for display purposes only. The user.username field may be used to login.

Example Request JSON

{
  "registration": {
    "applicationId": "10000000-0000-0002-0000-000000000001",
    "data": {
      "displayName": "Johnny",
      "favoriteSports": [
        "Football",
        "Basketball"
      ]
    },
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "roles": [
      "user",
      "community_helper"
    ],
    "timezone": "America/Chicago",
    "username": "johnny123"
  }
}

Response#

The response for this API contains the User Registration that was updated. Security sensitive fields will not be returned in the 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.

Response Body#

registration.applicationIdUUID

The Id of the Application that this registration is for.

registration.authenticationTokenString

The authentication token that may be used in place of the User's password when authenticating against this application represented by this registration.

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

registration.dataObject

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

registration.idUUID

The Id of this registration.

registration.insertInstantLong

The instant that this registration was created.

registration.lastLoginInstantLong

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

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

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

registration.timezoneString

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

registration.tokensMap<String,String>DEPRECATED

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.

registration.usernameString

The username of the User for this Application only.

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

registration.verifiedBoolean

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

registrationVerificationIdStringAvailable since 1.27.0

When registration verification is enabled, this value will be returned if the registration has not yet been verified.

When using FormField verification strategy, this is the first part of the pair of verification Ids, and the registrationVerificationOneTimeCode 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 registration.

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.

registrationVerificationOneTimeCodeStringAvailable since 1.49.2

A registration one time code that will be paired with the registrationVerificationId.

This value will only be present when when FormField is configured as the verification strategy. When present, this value 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.

Example Response JSON

{
  "registration": {
    "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
  }
}