Register API

On this page

The Register endpoint shows the self-service registration form on the hosted login pagesThe login, registration, password recovery, and multi-factor authentication pages that FusionAuth serves. A Theme controls the look of the pages.. After the user registers, FusionAuth completes the OAuth flow the same way the Authorize endpoint does, and redirects the browser to the redirect_uri.

To build a Register request, take an Authorize request and replace /oauth2/authorize with /oauth2/register. The Application must have self-service registration enabled. For more information, see Basic Registration Forms.

The Register endpoint registers users. To register OAuth clients, see Client Registration.

Request#

Redirect the browser to the Register endpoint from your application:

GET/oauth2/register?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&tenantId={tenantId}&scope=openid%20offline_access%20profile%20email

The Register endpoint doesn't accept the Tenant Id as a URL segment. Pass the tenantId as a query parameter.

Query Parameters#

client_id
  • Type: String
  • Required

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

code_challenge
  • Type: String
  • Optional
  • Available since 1.8.0

The code_challenge parameter as described in the Proof Key for Code Exchange by OAuth Public Clients (PKCE) specification. When this parameter is provided during the Authorization request, a corresponding code_verifier parameter is required on the subsequent POST to the /oauth2/token endpoint.

code_challenge_method
  • Type: String
  • Optional
  • Available since 1.8.0

The code_challenge_method parameter as described in the Proof Key for Code Exchange by OAuth Public Clients (PKCE) specification.

The possible values are:

  • S256 - SHA-256
dpop_jkt
  • Type: String
  • Optional
  • Available since 1.63.0

The dpop_jkt parameter can be provided to bind the authorization code to a DPoP key. When this parameter is provided during the Authorization request, a corresponding DPoP HTTP header is required on the subsequent POST to the /oauth2/token endpoint. DPoP is an Enterprise feature.

locale
  • Type: String
  • Optional

The locale to be used to render the registration page. This is useful if you already know the user's preferred locale before redirecting the user to FusionAuth. See the Theme Localization documentation for more information.

max_age
  • Type: Integer
  • Optional
  • Available since 1.60.0

An optional parameter that indicates the authenticated SSO session maximum age in seconds. This is called the Maximum Authentication Age in the OpenID specification.

A user with an SSO session older than the time specified by this parameter will be required to reauthenticate.

A value of 0 is equal to prompt=login.

Note that this parameter by itself does not guarantee that the user is reauthenticated. See OIDC Prompt Security Considerations for implementation details.

FusionAuth applies this parameter only when FusionAuth redirects the request to the Authorize endpoint, such as when the user already has an SSO session. When FusionAuth shows the registration form, FusionAuth ignores this parameter.

metaData.device.description
  • Type: String
  • Optional

A human readable description of the device used during login. This metadata is used to describe the refresh token that may be generated for this login request.

nonce
  • Type: String
  • Optional
  • Available since 1.5.0

The nonce parameter as described in the OpenID Connect core specification. When this parameter is provided during the Authorization request, the value will be returned in the id_token.

prompt
  • Type: String
  • Optional
  • Available since 1.60.0

An optional case sensitive space-delimited parameter for additional control of silent authentication, forced reauthentication, and consent prompts.

The possible values are:

  • none - No user interface is displayed. An error is returned if the user is not already authenticated.
  • login - The user will be prompted for authentication when there's an existing SSO session.
  • consent - Always prompt for consent from the user.

Note that prompt=login doesn't guarantee that the user is reauthenticated. See OIDC Prompt for implementation details, security considerations, limitations and example usage.

FusionAuth applies this parameter only when FusionAuth redirects the request to the Authorize endpoint, such as when the user already has an SSO session. When FusionAuth shows the registration form, FusionAuth ignores this parameter.

redirect_uri
  • Type: String
  • Required

The URI to redirect to upon a successful request. This URI must have been configured previously in the FusionAuth Application OAuth configuration. See Applications in the FusionAuth User Guide for additional information on configuring the redirect URIThe URL where the authorization server sends the browser after login, with an authorization code or an error..

resource
  • Type: String
  • Optional
  • Available since 1.67.0

The URI of the target resource serverThe API or service that accepts access tokens and returns protected data. A resource server validates each access token before responding. for the requested access token, per RFC 8707 (Resource Indicators for OAuth 2.0).

To provide multiple URIs, pass each URI as a separate parameter with the same name. The following validation rules are applied in order; any failure returns invalid_target and the authorization code is immediately invalidated:

  1. Each value must be an absolute URI and may not contain a fragment (#).
  2. All provided values must be present in the application's oauthConfiguration.authorizedResourceUris; any invalid value returns an invalid_target error.
  3. When oauthConfiguration.authorizedResourceUris is empty, this parameter is silently ignored.

Otherwise, the validated resource URIs are bound to the authorization code and carried forward to the token endpointThe OAuth 2.0 endpoint where an application exchanges a grant, such as an authorization code, for tokens. In FusionAuth, the token endpoint is /oauth2/token..

Caution

This field supports a maximum of 10,000 values.

response_mode
  • Type: String
  • Optional
  • Available since 1.11.0

Determines how the result parameters are to be returned to the caller. When this parameter is not provided the default response mode will be used based upon the response_type field.

The default when the response_type is set to code is query, the default when the response_type is set to token, token id_token or id_token is fragment.

The possible values are:

  • form_post
  • fragment
  • query - This response mode can only be used when the response_type is set to code.

In general, you only need to provide this parameter when you wish to use the form_post response mode.

For more detail on each mode, default values, and when each response_mode is appropriate, see Response Modes.

response_type
  • Type: String
  • Required

The requested response type.

For the Authorization Code Grant, set this value to code. For the Implicit Grant, use one of the values from the Implicit Grant Request.

scope
  • Type: String
  • Optional

If you are using OpenID Connect, the request must contain this parameter and at minimum it must contain openid. This parameter may contain multiple space separated scopes. For example, the value of openid offline_access provides two scopes on the request.

Example scopes which modify the behavior of the endpoint:

  • openid - This scope is used to request an id_token be returned in the response
  • offline_access - This scope is used to request a refresh_token be returned in the response

Learn more about scopes, including custom scopes.

state
  • Type: String
  • Optional

The optional state parameter. This is generally used as a Cross Site Request Forgery (CSRFAn attack in which a malicious site makes the user's browser send an unwanted request to a site where the user is logged in. The OAuth 2.0 state parameter protects the authorization flow from CSRF.) token or to provide deeplinking support. Any value provided in this field will be returned on a successful redirect. See OpenID Connect core specification for additional information on how this parameter may be utilized.

tenantId
  • Type: UUID
  • Required
  • Available since 1.8.0

The unique Tenant Id used for applying the proper theme.

user_code
  • Type: String
  • Optional
  • Available since 1.11.0

The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow.

The Register endpoint ignores the idp_hint and login_hint parameters. The registration form lists the Application's Identity Providers that create registrations, so the user can choose one.

Response#

FusionAuth shows the registration form only when the user has no SSO session. In the following cases, FusionAuth redirects the browser to the Authorize endpoint instead:

  • The Application doesn't have self-service registration enabled.
  • The user already has an SSO session. Authorize then logs the user in and redirects to the redirect_uri.

The redirect keeps the OAuth parameters from the request, except locale, idp_hint, and login_hint.

Response Codes

Code Description
200 The request was successful, and the response contains the registration form. When the client_id or redirect_uri is invalid, the response is an HTML error page instead.
302 The Application doesn't have self-service registration enabled, or the user has an SSO session. The request redirects to /oauth2/authorize. When the request has another error, such as a missing response_type, the request redirects to the redirect_uri with an error. For more information, see OAuth Error.
500 There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.
503 The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

When the user completes the registration form, FusionAuth redirects the browser to the redirect_uri. The following is an example redirect for the Authorization Code Grant, with line breaks added for readability:

Example HTTP Redirect Response
HTTP/1.1 302 Found
Location: https://piedpiper.com/callback?
           code=pU2DHOWjSCVh6NJKi1ClhBYNKfuqbZVT
           &iss=https%3A%2F%2Fpiedpiper.fusionauth.io
           &locale=en_US
           &state=abc123
           &userState=Authenticated

Exchange the code for tokens with the Token endpoint, the same as after a login. For the Implicit Grant, FusionAuth returns the tokens in the redirect. For the Implicit Grant parameters, see the Authorize Implicit Grant Request.

Redirect Parameters#

code
  • Type: String
  • Required

The authorization code.

iss
  • Type: String
  • Optional

The authorization server's issuer identifier as defined by RFC 9207. This value is the tenant's configured issuer and should be validated by the client against the authorization server metadata to prevent mix-up attacks.

See Issuer Validation for implementation guidance.

Available since 1.69.0
locale
  • Type: String
  • Optional

The locale that was to render the login page, or a previously selected locale by the user during a previous session. This may be useful to know in your own application so you can continue to localize the interface for the language the user selected while on the FusionAuth login page. See the Theme Localization documentation for more information.

state
  • Type: String
  • Optional

The state that was provided on the Authorization request. This parameter will be omitted if the state request parameter was not provided.

userState
  • Type: String
  • Optional

The FusionAuth user state. This value serves as a hint for the user's registration and verification status suitable for message customization and similar uses. userState should not be used to make any security decisions for the user.

The possible values are:

  • Authenticated - The user is successfully authenticated for the requested application.
  • AuthenticatedNotRegistered - The user is successfully authenticated, but not registered for the requested application.
  • AuthenticatedNotVerified - The user is successfully authenticated, but the user's email address and/or phone number have not been verified.
  • AuthenticatedRegistrationNotVerified - The user is successfully authenticated and registered, but the registration has not been verified for the requested application.

For a CIMD client, the value is always AuthenticatedNotRegistered, because FusionAuth does not register users for CIMD clients.