# Register API

API documentation for the FusionAuth Register OAuth2 endpoint, which starts self-service user registration on the hosted pages.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

The Register endpoint shows the self-service registration form on the [hosted login pages](https://fusionauth.io/docs/concepts/integration-points.md#hosted-login-pages). After the user registers, FusionAuth completes the OAuth flow the same way the [Authorize](https://fusionauth.io/docs/apis/oauth/authorize.md) 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](https://fusionauth.io/docs/users/register/basic-registration-forms.md).

The Register endpoint registers users. To register OAuth clients, see [Client Registration](https://fusionauth.io/docs/authentication/oauth/client-registration.md).

## 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)](https://tools.ietf.org/html/rfc7636) 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)](https://tools.ietf.org/html/rfc7636) 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](https://fusionauth.io/docs/authentication/oauth/dpop.md) is an Enterprise feature.

`locale`

*   Type: `String`
*   Optional

The [locale](https://fusionauth.io/docs/apis/data-types.md#locales) 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](https://fusionauth.io/docs/theme/localization.md) 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](https://fusionauth.io/docs/authentication/oauth/prompt.md#security-considerations) for implementation details.

FusionAuth applies this parameter only when FusionAuth redirects the request to the [Authorize](https://fusionauth.io/docs/apis/oauth/authorize.md) 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](https://openid.net/specs/openid-connect-core-1_0.html) 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](https://fusionauth.io/docs/authentication/oauth/prompt.md#security-considerations) for implementation details, security considerations, limitations and example usage.

FusionAuth applies this parameter only when FusionAuth redirects the request to the [Authorize](https://fusionauth.io/docs/apis/oauth/authorize.md) 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 URI](https://fusionauth.io/docs/authentication/oauth/url-validation.md).

`resource`

*   Type: `String`
*   Optional
*   Available since `1.67.0`

The URI of the target [resource server](https://fusionauth.io/docs/authentication/oauth/tokens.md#validate-an-access-token) for the requested access token, per [RFC 8707 (Resource Indicators for OAuth 2.0)](https://www.rfc-editor.org/rfc/rfc8707.html).

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 endpoint](https://fusionauth.io/docs/apis/oauth/token.md).

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](https://fusionauth.io/docs/authentication/oauth/response-modes.md).

`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](https://fusionauth.io/docs/apis/oauth/authorize.md#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.](https://fusionauth.io/docs/authorization/oauth-scopes.md)

`state`

*   Type: `String`
*   Optional

The optional state parameter. This is generally used as a Cross Site Request Forgery ([CSRF](https://fusionauth.io/docs/apis/oauth/authorize.md)) token or to provide deeplinking support. Any value provided in this field will be returned on a successful redirect. See [OpenID Connect core](https://openid.net/specs/openid-connect-core-1_0.html) 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](https://fusionauth.io/docs/apis/oauth/authorize.md) 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](https://fusionauth.io/docs/apis/oauth/oauth-error.md). |
| 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

```plaintext
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](https://fusionauth.io/docs/apis/oauth/token.md) 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](https://fusionauth.io/docs/apis/oauth/authorize.md#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](https://www.rfc-editor.org/rfc/rfc9207). 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](https://fusionauth.io/docs/authentication/oauth/issuer-validation.md) for implementation guidance.

Available since `1.69.0`

`locale`

*   Type: `String`
*   Optional

The [locale](https://fusionauth.io/docs/apis/data-types.md#locales) 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](https://fusionauth.io/docs/theme/localization.md) 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](https://fusionauth.io/docs/authentication/oauth/client-registration.md#client-id-metadata-documents), the value is always `AuthenticatedNotRegistered`, because FusionAuth does not register users for CIMD clients.

Related

[APIs Authorize API API documentation for the FusionAuth Authorize OAuth2 endpoint. fusionauth apirest apihttp api](https://fusionauth.io/docs/apis/oauth/authorize.md)

[APIs Client Secret Reference Client Secret reference for FusionAuth OAuth2 endpoints. fusionauth apirest apihttp api](https://fusionauth.io/docs/apis/oauth/client-secret.md)

[APIs Device API API documentation for the FusionAuth Device OAuth2 endpoint. fusionauth apirest apihttp api](https://fusionauth.io/docs/apis/oauth/device.md)

[APIs Introspect API API documentation for the FusionAuth Introspect OAuth2 endpoint. fusionauth apirest apihttp api](https://fusionauth.io/docs/apis/oauth/introspect.md)
---

## Other pages in OAuth

> For the full index of this section, see [Apis](https://fusionauth.io/docs/llms-apis.txt).

- [Authorize API](https://fusionauth.io/docs/apis/oauth/authorize.md): API documentation for the FusionAuth Authorize OAuth2 endpoint.
- [Client Secret Reference](https://fusionauth.io/docs/apis/oauth/client-secret.md): Client Secret reference for FusionAuth OAuth2 endpoints.
- [Device API](https://fusionauth.io/docs/apis/oauth/device.md): API documentation for the FusionAuth Device OAuth2 endpoint.
- [OAuth2 API](https://fusionauth.io/docs/apis/oauth.md): API documentation for the FusionAuth OAuth 2.0 and OpenID Connect endpoints.
- [Introspect API](https://fusionauth.io/docs/apis/oauth/introspect.md): API documentation for the FusionAuth Introspect OAuth2 endpoint.
- [JSON Web Key Set (JWKS) API](https://fusionauth.io/docs/apis/oauth/jwks.md): API documentation for the FusionAuth JSON Web Key Set (JWKS) OAuth2 endpoint.
- [Logout API](https://fusionauth.io/docs/apis/oauth/logout.md): API documentation for the FusionAuth Logout OAuth2 endpoint.
- [OAuth Error Reference](https://fusionauth.io/docs/apis/oauth/oauth-error.md): OAuthError reference for FusionAuth OAuth2 endpoints.
- [OpenID Configuration API](https://fusionauth.io/docs/apis/oauth/openid-configuration.md): API documentation for the FusionAuth OpenID Configuration OAuth2 endpoint.
- [Token API](https://fusionauth.io/docs/apis/oauth/token.md): API documentation for the FusionAuth Token OAuth2 endpoint.
- [UserInfo API](https://fusionauth.io/docs/apis/oauth/userinfo.md): API documentation for the FusionAuth UserInfo OAuth2 endpoint.
