FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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)

    • Create a User and Registration (combined)

    • Retrieve a User Registration

    • Update a User Registration

    • Delete a User Registration

    • Verify a User Registration

    • Resend a User Registration Verification Email

    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

    URI

    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.

    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.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. Please review the limits on data field types as you plan for and build your custom data schema.

    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. This username cannot be used to login. It is for display purposes only. The user.username field may be used to login.

    skipRegistrationVerification [Boolean] Optional defaults to false

    Indicates to FusionAuth that it should skip registration verification even if it is enabled for the Application.

    Setting this to true will set registration.verified to true as well.

    Example Request JSON
    
    {
      "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.

    Table 1. 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 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 provided one has expired. A refresh token will be generated and returned if application.loginConfiguration.generateRefreshTokens is true for the corresponding application.

    refreshTokenId [String] Available since 1.37.0

    When the refreshToken is returned in the response, this field will also be returned. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the Refresh Token API.

    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>] 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.username [String]

    The username of the User for this Application 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).

    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"
      },
      "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

    URI

    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

    disableDomainBlock [Boolean] Optional defaults to false Available since 1.30.0

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

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

    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 or US/Mountain
    registration.username [String] Optional

    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.

    sendSetPasswordEmail [Boolean] Optional defaults to false

    If true, FusionAuth will send the User an email asking them to set their password. The Email Template that is used is the one specified in the setPasswordEmailTemplateId configured in the Application, or, if that is not configured, the same field in the Tenant.

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

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

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

    skipRegistrationVerification [Boolean] Optional defaults to false

    Indicates to FusionAuth that it should skip registration verification even if it is enabled for the Application.

    skipVerification [Boolean] 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 as YYYY-MM-DD.

    user.data [Object] Optional

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

    user.data.email [String] Optional

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

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

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

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

    • salted-md5

    • salted-sha256

    • salted-hmac-sha256

    • salted-pbkdf2-hmac-sha256

    • salted-pbkdf2-hmac-sha256-512   Available since 1.34.0

    • bcrypt

      You can also create your own password encryptor. See the Custom Password Hashing 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 plain text password. This password will be hashed and the provided value will never be stored and cannot be retrieved.

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

    user.passwordChangeRequired [Boolean] Optional defaults to false

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

    user.preferredLanguages [Array<String>] Optional

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

    user.timezone [String] Optional

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

    America/Denver or US/Mountain
    user.twoFactor.methods[x].authenticator.algorithm [String] Optional

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

    user.twoFactor.methods[x].authenticator.codeLength [Integer] Optional

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

    user.twoFactor.methods[x].authenticator.timeStep [Integer] Optional

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

    user.twoFactor.methods[x].email [String] Optional

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

    user.twoFactor.methods[x].method [String] Optional

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

    • authenticator

    • email

    • sms

    user.twoFactor.methods[x].mobilePhone [String] Optional

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

    user.twoFactor.methods[x].secret [String] Optional

    A base64 encoded secret

    This field is required when method is authenticator.

    users.twoFactorDelivery [String] Optional defaults to None Deprecated

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

    The possible values are:

    • None

    • TextMessage

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

      Removed in version 1.26.0

    user.twoFactorEnabled [Boolean] Optional defaults to false Deprecated

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

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

    Removed in version 1.26.0

    user.twoFactorSecret [String] Optional Deprecated

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

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

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

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

    Removed in version 1.26.0

    user.username [String] Optional

    The username of the User.

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

    Response

    The response for this API contains the User and the User Registration that were created. Security sensitive fields will not be returned in the response.

    Table 2. Response Codes
    Code Description

    200

    The request was successful. The response will contain a JSON body.

    400

    The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.

    401

    You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

    500

    There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

    503

    The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

    Response Body

    refreshToken [String] Available since 1.17.0

    The refresh token that can be used to obtain a new access token once the provided one has expired. A refresh token will be generated and returned if application.loginConfiguration.generateRefreshTokens is true for the corresponding application.

    refreshTokenId [String] Available since 1.37.0

    When the refreshToken is returned in the response, this field will also be returned. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the Refresh Token API.

    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>] 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.username [String]

    The username of the User for this Application. It is for display purposes only.

    registration.verified [Boolean]

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

    For additional information, see these tutorials:

    • Email Verification

    • Registration Verification

    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.breachedPasswordLastCheckedInstant [Long]

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

    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.data.email [String]

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

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

    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.

    user.twoFactor.methods[x].authenticator.algorithm [String]

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

    user.twoFactor.methods[x].authenticator.codeLength [Integer]

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

    user.twoFactor.methods[x].authenticator.timeStep [Integer]

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

    user.twoFactor.methods[x].email [String]

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

    user.twoFactor.methods[x].id [String]

    The unique Id of the method.

    user.twoFactor.methods[x].lastUsed [Boolean]

    true if this method was used most recently.

    user.twoFactor.methods[x].method [String]

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

    • authenticator

    • email

    • sms

    user.twoFactor.methods[x].mobilePhone [String]

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

    user.twoFactor.methods[x].secret [String]

    A base64 encoded secret

    user.twoFactorDelivery [String] Deprecated

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

    The possible values are:

    • None

    • TextMessage

      Removed in version 1.26.0

    user.twoFactorEnabled [Boolean] Deprecated

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

    Removed in version 1.26.0

    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.

    For additional information, see these tutorials:

    • Email Verification

    • Registration Verification

    Example Response JSON
    
    {
      "refreshToken": "x7alP0xYDx86sPQfx01ERyai0DXAK1OzA8xUVvxRi_Gug3pfx2s4pg",
      "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"
      },
      "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",
        "twoFactor": {
          "methods": [
            {
              "authenticator": {
                "algorithm": "HmacSHA1",
                "codeLength": 6,
                "timeStep": 30
              },
              "id": "35VW",
              "method": "authenticator"
            },
            {
              "id": "V7SH",
              "method": "sms",
              "mobilePhone": "555-555-5555"
            },
            {
              "email": "example@fusionauth.io",
              "id": "7K2G",
              "method": "email"
            }
          ]
        },
        "usernameStatus": "ACTIVE",
        "username": "johnny123",
        "verified": true
      }
    }

    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

    URI

    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.

    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. This status will also be returned if a paid FusionAuth license is required and is not present.

    401

    You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

    404

    The object you requested doesn’t exist. The response will be empty.

    500

    There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

    503

    The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

    Response Body

    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>] 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.username [String]

    The username of the User for this Application 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.

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

    Update a User Registration

    This API is used to update an existing User Registration.

    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

    URI

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

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

    Available since 1.39.0

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

    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 an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

     

    Request Parameters

    applicationId [UUID] Required Available in 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.

    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.

    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.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. Please review the limits on data field types as you plan for and build your custom data schema.

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

    Table 4. 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.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>] 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.username [String]

    The username of the User for this Application 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.

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

    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

    URI

    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.

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

    URI

    POST /api/user/verify-registration

    URI

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

    Request Parameters

    verificationId [String] Required Deprecated

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

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

    Request Body

    oneTimeCode [String] Optional Available since 1.27.0

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

    This field is required when the registration verification strategy on the Application is set to Form field.

    verificationId [String] Required Available since 1.27.0

    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.

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

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

    Request Headers

    X-FusionAuth-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.

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

    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

    URI

    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

    URI

    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 to false.

    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.

    Table 7. Response Codes
    Code Description

    200

    The request was successful. The response will contain a JSON body if an API key was used for authentication. If no API key was provided no response body will be returned.

    400

    The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.

    401

    You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

    403

    The Verify Registration feature has been disabled. FusionAuth is unable to send Email Verification emails.

    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

    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.

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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates