User Registration APIs
Overview
This page contains the APIs that are used to manage User Registrations. A registration is the association between a User and an Application that they log into. Here are the APIs:
Create a User Registration (for an existing user)
This API is used to create a new User Registration for an existing User. If the User has already created their global account but is now creating an account for an Application, this is the API you will use to create the new account. You must specify the User Id being registered on the URI. The Id of the Application the User is registering for is sent in the request body.
Request
Create a User Registration for an existing User
POST /api/user/registration/{userId}
Request Parameters
- userId [UUID] Required
-
The Id of the User that is registering for the Application.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
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
- generateAuthenticationToken [Boolean] Optional defaults to
false
-
Determines if FusionAuth should generate an Authentication Token for this registration.
- registration.applicationId [UUID] Required
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String] Optional
-
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.data [Object] Optional
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.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.
- registration.id [UUID] Optional defaults to secure random UUID
-
The Id of this registration. If not specified a secure random UUID will be generated.
- registration.roles [Array<String>] Optional
-
The list of roles that the User has for this Application.
- registration.timezone [String] Optional
-
The User’s preferred timezone for this Application registration. The string must be in an IANA time zone format.
- registration.username [String] Optional
-
The username of the User for this Application only.
- skipRegistrationVerification [Boolean] Optional defaults to
false
-
Indicates to FusionAuth that it should skip registration verification even if it is enabled for the Application.
{
"registration": {
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"preferredLanguages": [
"en",
"fr"
],
"roles": [
"user",
"community_helper"
],
"timezone": "America/Chicago",
"username": "johnny123"
}
}
Response
The response for this API contains the User Registration that was created. Security sensitive fields will not be returned in the response.
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 user specified by Id in the request parameter does not 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
- refreshToken [String] Available since 1.17.0
-
The refresh token that can be used to obtain a new access token once the provide one has expired.
- registration.applicationId [UUID]
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String]
-
The authentication token that may be used in place of the User’s password when authenticating against this application represented by this registration.
- registration.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.
- registration.data [Object]
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.id [UUID]
-
The Id of this registration.
- registration.insertInstant [Long]
-
The instant that this registration was created.
- registration.lastLoginInstant [Long]
-
The instant that the User last logged into the Application for this registration.
- registration.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.
- registration.roles [Array<String>]
-
The list of roles that the User has for this registration.
- registration.timezone [String]
-
The User’s preferred timezone for this registration. The string will be in an IANA time zone format.
- registration.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. - registration.username [String]
-
The username of the User for this registration only.
- registration.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.
-
- registration.verified [Boolean]
-
This value indicates if this User’s registration has been verified.
- token [String] Available since 1.16.0
-
The access token, this string is an encoded JSON Web Token (JWT).
{
"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",
"tokens": {
"Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
"19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
},
"username": "johnny123",
"usernameStatus": "ACTIVE"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikg3Q3hSNldtMDRUcm1zYXd0SF9BVkEwZTVaLS1UR1lUIn0.eyJhdWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDEiLCJleHAiOjE1ODY4ODEzMzYsImlhdCI6MTU4Njg4MTI3NiwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlJFR0lTVFJBVElPTiIsImVtYWlsIjoiZW1haWxAdGVzdC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoidXNlcm5hbWUiLCJhcHBsaWNhdGlvbklkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxIiwicm9sZXMiOlt7ImlkIjoiNjM1YzU3ZmMtNzMwZC00OWY2LWEzM2YtZGQ1YTlmZTRlMjc5IiwiaXNEZWZhdWx0IjpmYWxzZSwiaXNTdXBlclJvbGUiOmZhbHNlLCJuYW1lIjoicm9sZSAxIn1dfQ.9IuprQIe2SGYWPV6nL_XNBEpb4XaTSBBxiyLAWtg4pg"
}
Create a User and Registration (combined)
This API is used to create a new User and a User Registration in a single request. This is useful if for example you have a main website that User’s create their account on initially. The User is technically creating their global User object and a User Registration for that website (i.e. that Application). In this case, you will want to create the User and the User Registration in a single step. This is the API to use for that. You can optionally still provide an Id for the new User on the URI. If you don’t specify an Id for the User, FusionAuth will create one for you.
Request
Create a User and a User Registration in a single API call
POST /api/user/registration/{userId}
Request Parameters
- userId [UUID] Optional
-
The Id to use for the new User. If you don’t specify this, FusionAuth will generate a random UUID.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
The unique Id of the tenant used to scope this API request.
When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
This request requires that you specify both the User object and the User Registration object in the request body. The fields for each are listed below.
Request Body
- generateAuthenticationToken [Boolean] Optional defaults to
false
-
Determines if FusionAuth should generate an Authentication Token for this registration.
- registration.applicationId [UUID] Required
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String] Optional
-
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.data [Object] Optional
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.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.
- registration.id [UUID] Optional
-
The Id of this registration. If this is not specified, FusionAuth will create a random UUID for you.
- registration.roles [Array<String>] Optional
-
The list of roles that the User has for this Application.
- registration.timezone [String] Optional
-
The User’s preferred timezone for this Application registration. The format is not enforced, however it is recommended to use a timezone in the TZ format such as
America/Denver
orUS/Mountain
- registration.username [String] Optional
-
The username of the User for this Application only.
- sendSetPasswordEmail [Boolean] Optional defaults to
false
-
Whether or not the User is sent an email asking them to setup their password. This is useful if someone else is creating an account for a User with an Application.
The Email Template that is used is configured in the Tenant setting for Setup 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.If the SMTP email configuration is not complete, or disabled, this value is ignored.
- skipRegistrationVerification [Boolean] Optional defaults to
false
-
Indicates to FusionAuth that it should skip registration verification even if it is enabled for the Application.
- skipVerification [String] Optional defaults to
false
-
Whether or not email verification should be skipped or not. In some cases, you might want to verify User’s emails and in other cases you won’t. This flag controls that behavior.
- user.birthDate [String] Optional
-
An
ISO-8601
formatted date of the User’s birthdate such asYYYY-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.
- 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 thePasswordEncryptor
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 plain texts password. This password will be hashed and the provided value will never be stored and cannot be retrieved.
This field is optional only if
sendSetPasswordEmail
is set totrue
. By defaultsendSetPasswordEmail
isfalse
, and then this field will be required. - user.passwordChangeRequired [Boolean] Optional defaults to
false
-
Indicates that the User’s password needs to be changed during their next login attempt.
- user.preferredLanguages [Array<String>] Optional
-
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.
- user.timezone [String] Optional
-
The User’s preferred timezone. The string must be in an IANA time zone format. For example:
America/Denver
orUS/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 validmobilePhone
.
-
- user.twoFactorEnabled [Boolean] Optional defaults to
false
-
Determines if the User has two factor authentication enabled for their account or not.
See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API.
- user.twoFactorSecret [String] Optional
-
The Base64 encoded secret used to generate Two Factor verification codes.
You may optionally use value provided in the
secret
field returned by the Two Factor Secret API instead of generating this value yourself.Unless you are using
TextMessage
as your delivery type, ensure you are able to share the secret with the User before enabling Two Factor authentication. Beginning in version 1.17.0, if you do create a User withTextMessage
set as thetwoFactorDelivery
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 thetwoFactorDelivery
this value will be required. - user.username [String] Optional
-
The username of the User.
{
"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"
},
"sendSetPasswordEmail": false,
"skipVerification": false,
"user": {
"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",
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"preferredLanguages": [
"en",
"fr"
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123"
}
}
Response
The response for this API contains the User and the User Registration that were created. Security sensitive fields will not be returned in the response.
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. |
Response Body
- refreshToken [String] Available since 1.17.0
-
The refresh token that can be used to obtain a new access token once the provide one has expired.
- registration.applicationId [UUID]
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String]
-
The authentication token that may be used in place of the User’s password when authenticating against this application represented by this registration.
- registration.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.
- registration.data [Object]
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.id [UUID]
-
The Id of this registration.
- registration.insertInstant [Long]
-
The instant that this registration was created.
- registration.lastLoginInstant [Long]
-
The instant that the User last logged into the Application for this registration.
- registration.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.
- registration.roles [Array<String>]
-
The list of roles that the User has for this registration.
- registration.timezone [String]
-
The User’s preferred timezone. The string will be in an IANA time zone format.
- registration.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. - registration.username [String]
-
The username of the User for this registration only.
- registration.verified [Boolean]
-
This value indicates if this User’s registration has been verified.
- registration.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.
-
- token [String] Available since 1.16.0
-
The access token, this string is an encoded JSON Web Token (JWT).
- 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.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.timezone [String]
-
The User’s preferred timezone. The string will be in an IANA time zone format.
- 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.
{
"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",
"tokens": {
"Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
"19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
},
"username": "johnny123",
"usernameStatus": "ACTIVE"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikg3Q3hSNldtMDRUcm1zYXd0SF9BVkEwZTVaLS1UR1lUIn0.eyJhdWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDEiLCJleHAiOjE1ODY4ODEzMzYsImlhdCI6MTU4Njg4MTI3NiwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlJFR0lTVFJBVElPTiIsImVtYWlsIjoiZW1haWxAdGVzdC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoidXNlcm5hbWUiLCJhcHBsaWNhdGlvbklkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxIiwicm9sZXMiOlt7ImlkIjoiNjM1YzU3ZmMtNzMwZC00OWY2LWEzM2YtZGQ1YTlmZTRlMjc5IiwiaXNEZWZhdWx0IjpmYWxzZSwiaXNTdXBlclJvbGUiOmZhbHNlLCJuYW1lIjoicm9sZSAxIn1dfQ.9IuprQIe2SGYWPV6nL_XNBEpb4XaTSBBxiyLAWtg4pg",
"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"
],
"timezone": "America/Denver",
"tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
}
Retrieve a User Registration
This API is used to retrieve a single User Registration. This is the information about a User for a single Application.
Request
Retrieve a User Registration for the User Id and Application Id
GET /api/user/registration/{userId}/{applicationId}
Request Parameters
- applicationId [UUID] Required
-
The Id of the Application that the User is registered for.
- userId [UUID] Required
-
The Id of the User whose registration is being retrieved.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
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.
Response
The response for this API contains the User Registration.
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. |
Response Body
- refreshToken [String] Available since 1.17.0
-
The refresh token that can be used to obtain a new access token once the provide one has expired.
- registration.applicationId [UUID]
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String]
-
The authentication token that may be used in place of the User’s password when authenticating against this application represented by this registration.
- registration.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.
- registration.data [Object]
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.id [UUID]
-
The Id of this registration.
- registration.insertInstant [Long]
-
The instant that this registration was created.
- registration.lastLoginInstant [Long]
-
The instant that the User last logged into the Application for this registration.
- registration.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.
- registration.roles [Array<String>]
-
The list of roles that the User has for this registration.
- registration.timezone [String]
-
The User’s preferred timezone for this registration. The string will be in an IANA time zone format.
- registration.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. - registration.username [String]
-
The username of the User for this registration only.
- registration.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.
-
- registration.verified [Boolean]
-
This value indicates if this User’s registration has been verified.
- token [String] Available since 1.16.0
-
The access token, this string is an encoded JSON Web Token (JWT).
{
"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",
"tokens": {
"Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
"19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
},
"username": "johnny123",
"usernameStatus": "ACTIVE"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikg3Q3hSNldtMDRUcm1zYXd0SF9BVkEwZTVaLS1UR1lUIn0.eyJhdWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDEiLCJleHAiOjE1ODY4ODEzMzYsImlhdCI6MTU4Njg4MTI3NiwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlJFR0lTVFJBVElPTiIsImVtYWlsIjoiZW1haWxAdGVzdC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoidXNlcm5hbWUiLCJhcHBsaWNhdGlvbklkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxIiwicm9sZXMiOlt7ImlkIjoiNjM1YzU3ZmMtNzMwZC00OWY2LWEzM2YtZGQ1YTlmZTRlMjc5IiwiaXNEZWZhdWx0IjpmYWxzZSwiaXNTdXBlclJvbGUiOmZhbHNlLCJuYW1lIjoicm9sZSAxIn1dfQ.9IuprQIe2SGYWPV6nL_XNBEpb4XaTSBBxiyLAWtg4pg"
}
Update a User Registration
This API is used to update a User Registration for a User. This API is used to update the User’s registration for a specific Application. You must specify the User Id for the User that is updating their information on the URI. The Id of the Application the User is updating their information for is sent in the request body. This API doesn’t merge the existing User Registration and your new data. It replaces the existing User Registration with your new data.
Request
PUT /api/user/registration/{userId}
PATCH /api/user/registration/{userId}
Available since 1.12.0
When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A
null
value can be used to remove a value. Patching anArray
will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.
Request Parameters
- userId [UUID] Required
-
The Id of the User that is updating their User Registration for the Application.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
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
- generateAuthenticationToken [Boolean] Optional defaults to
false
-
Determines if FusionAuth should generate an Authentication Token for this registration.
- registration.applicationId [UUID] Required
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String] Optional
-
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.data [Object] Optional
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.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.
- registration.roles [Array<String>] Optional
-
The list of roles that the User has for this Application.
- registration.timezone [String] Optional
-
The User’s preferred timezone for this Application registration. The string must be in an IANA time zone format.
- registration.username [String] Optional
-
The username of the User for this Application only.
{
"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.
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. |
Response Body
- refreshToken [String] Available since 1.17.0
-
The refresh token that can be used to obtain a new access token once the provide one has expired.
- registration.applicationId [UUID]
-
The Id of the Application that this registration is for.
- registration.authenticationToken [String]
-
The authentication token that may be used in place of the User’s password when authenticating against this application represented by this registration.
- registration.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.
- registration.data [Object]
-
An object that can hold any information about the User for this registration that should be persisted.
- registration.id [UUID]
-
The Id of this registration.
- registration.insertInstant [Long]
-
The instant that this registration was created.
- registration.lastLoginInstant [Long]
-
The instant that the User last logged into the Application for this registration.
- registration.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.
- registration.roles [Array<String>]
-
The list of roles that the User has for this registration.
- registration.timezone [String]
-
The User’s preferred timezone for this registration. The string will be in an IANA time zone format.
- registration.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. - registration.username [String]
-
The username of the User for this registration only.
- registration.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.
-
- registration.verified [Boolean]
-
This value indicates if this User’s registration has been verified.
- token [String] Available since 1.16.0
-
The access token, this string is an encoded JSON Web Token (JWT).
{
"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",
"tokens": {
"Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
"19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
},
"username": "johnny123",
"usernameStatus": "ACTIVE"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikg3Q3hSNldtMDRUcm1zYXd0SF9BVkEwZTVaLS1UR1lUIn0.eyJhdWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDEiLCJleHAiOjE1ODY4ODEzMzYsImlhdCI6MTU4Njg4MTI3NiwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlJFR0lTVFJBVElPTiIsImVtYWlsIjoiZW1haWxAdGVzdC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoidXNlcm5hbWUiLCJhcHBsaWNhdGlvbklkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxIiwicm9sZXMiOlt7ImlkIjoiNjM1YzU3ZmMtNzMwZC00OWY2LWEzM2YtZGQ1YTlmZTRlMjc5IiwiaXNEZWZhdWx0IjpmYWxzZSwiaXNTdXBlclJvbGUiOmZhbHNlLCJuYW1lIjoicm9sZSAxIn1dfQ.9IuprQIe2SGYWPV6nL_XNBEpb4XaTSBBxiyLAWtg4pg"
}
Delete a User Registration
This API is used to delete a single User Registration.
Request
Delete a User Registration by providing the User Id and the Application Id
DELETE /api/user/registration/{userId}/{applicationId}
Request Parameters
- applicationId [UUID] Required
-
The Id of the Application for which the User will no longer be registered.
- userId [UUID] Required
-
The Id of the User whose registration is being removed.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
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.
Response
The response for this API does not contain a body. It only contains one of the status codes listed below.
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. |
Verify a User Registration
This API is used to mark a User Registration as verified. This is usually called after the User receives the registration verification email after they register and they click the link in the email.
Request
Verifies the User Registration using a verificationId
.
POST /api/user/verify-registration/{verificationId}
Request Parameters
- verificationId [String] Required
-
The verification Id generated by FusionAuth used to verify the User’s registration is valid by ensuring they have access to the provided email address.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
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.
Response
The response does not contain a body. It only contains one of the status codes below.
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. |
404 |
The User does not exist or is not registered to the requested Application. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 |
The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Resend a User Registration Verification Email
This API is used to resend the registration 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.
Request
Resend the registration verification email
PUT /api/user/verify-registration?applicationId={applicationId}&email={email}
Request Parameters
- applicationId [UUID] Required
-
The unique Id of the Application for this User registration.
- email [String] Required
-
The email address used to uniquely identify the User.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
The unique Id of the tenant used to scope this API request.
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.
Resend the registration verification email using an API key
PUT /api/user/verify-registration?applicationId={applicationId}&email={email}&sendVerifyRegistrationEmail={sendVerifyRegistrationEmail}
Request Parameters
- applicationId [UUID] Required
-
The unique Id of the Application for this User registration.
- email [String] Required
-
The email address used to uniquely identify the User.
- sendVerifyRegistrationEmail [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 tofalse
.
This may be useful if you need to integrate the Registration Verification process using a third party messaging service.
Request Headers
- X-FusionAuth-TenantId [String] Optional
-
The unique Id of the tenant used to scope this API request.
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.
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.
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 Registration feature 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. |
Response Body
- verificationId [String]
-
The Registration Verification Id that was generated by this API request. This identifier may be used by the Verify a User Registration API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned.
{
"verificationId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}