> For the complete documentation index, see [llms.txt](/docs/llms.txt) # Authorize | FusionAuth Docs API documentation for the FusionAuth Authorize OAuth2 endpoint. # Authorize This is an implementation of the Authorization endpoint as defined by the [IETF RFC 6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1). ## Authorization Code Grant Request[#](#authorization-code-grant-request) To begin the Authorization Code Grant you will redirect to the Authorization endpoint from your application. GET/oauth2/authorize?client\_id={client\_id}&redirect\_uri={redirect\_uri}&response\_type=code&tenantId={tenantId}&scope=openid%20offline\_access%20profile%20email ### Request Headers[#](#request-headers) `Authorization`Stringoptional An optional request header that enables using an existing access token (JWT) to bootstrap the SSO session. For more information and examples, see [Bootstrapping SSO](/docs/lifecycle/authenticate-users/single-sign-on#bootstrapping-sso). ### Request Parameters[#](#request-parameters) `client_id`Stringrequired The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. `code_challenge`StringoptionalAvailable 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`StringoptionalAvailable 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`StringoptionalAvailable 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](/docs/lifecycle/authenticate-users/oauth/dpop) is an Enterprise feature. `idp_hint`UUIDoptionalAvailable since 1.19.0 An optional unique Identity Provider Id that can allow you to bypass the FusionAuth login page. Adding this request parameter will cause the FusionAuth login page to be skipped, and instead a `302` will be returned with a `Location` header of the IdP login URL. The end result is functionally equivalent to the end user clicking on the Login with Pied Piper button, or entering their email address when using the IdP configuration with managed domains. `locale`Stringoptional The [locale](/docs/reference/data-types#locales) to be used to render the login page. This is useful if you already know the user's preferred locale before redirecting the user to FusionAuth. See the [Theme Localization](/docs/customize/look-and-feel/localization) documentation for more information. `login_hint`StringoptionalAvailable since 1.19.0 An optional email address or top level domain that can allow you to bypass the FusionAuth login page when using managed domains. If using managed domains, adding this request parameter will cause the FusionAuth login page to be skipped, and instead a `302` will be returned with a `Location` header of the IdP login URL. The end result is functionally equivalent to the end entering their email address when using the IdP configuration with managed domains. If not using managed domains, providing an email address using this parameter prepopulates the email address in the login page. `max_age`IntegeroptionalAvailable 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](/docs/lifecycle/authenticate-users/oauth/prompt#security-considerations) for implementation details. `metaData.device.description`Stringoptional 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`StringoptionalAvailable 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`StringoptionalAvailable 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](/docs/lifecycle/authenticate-users/oauth/prompt#security-considerations) for implementation details, security considerations, limitations and example usage. `redirect_uri`Stringrequired 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. `resource`StringoptionalAvailable since 1.67.0 The URI of the target resource server 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. `response_mode`StringoptionalAvailable 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. `response_type`Stringrequired The requested response type. For the Authorization Code Grant, this value must be set to `code`. `scope`Stringoptional 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.](/docs/lifecycle/authenticate-users/oauth/scopes) `state`Stringoptional The optional state parameter. This is generally used as a Cross Site Request Forgery (CSRF) 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`UUIDrequiredAvailable since 1.8.0 The unique Tenant Id used for applying the proper theme. `user_code`StringoptionalAvailable 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. ### Response[#](#response) *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. The user is not logged in, the response will contain an HTML form to collect login credentials. | | 302 | The requested user is already logged in, the request will redirect to the location specified in the `redirect_uri` on the request. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors or errors on the redirect URI. The error responses are covered in the [OAuth Error section](/docs/apis/oauth/oauth-error) of the API documentation. | | 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. | The following is an example HTTP 302 redirect, line breaks added to improve readability. Example HTTP Redirect Response ``` HTTP/1.1 302 Found Location: https://piedpiper.com/callback? code=pU2DHOWjSCVh6NJKi1ClhBYNKfuqbZVT &locale=fr &state=abc123 &userState=Authenticated ``` ### Redirect Parameters[#](#redirect-parameters) `code`Stringrequired The authorization code. `locale`Stringoptional The [locale](/docs/reference/data-types#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](/docs/customize/look-and-feel/localization) documentation for more information. `state`Stringoptional The state that was provided on the Authorization request. This parameter will be omitted if the **state** request parameter was not provided. `userState`Stringoptional 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. ## Implicit Grant Request[#](#implicit-grant-request) To begin the Implicit Grant you will redirect to the Authorization endpoint from your application. GET/oauth2/authorize?client\_id={client\_id}&redirect\_uri={redirect\_uri}&response\_type=token%20id\_token&tenantId={tenantId} ### Request Headers[#](#request-headers-1) `Authorization`Stringoptional An optional request header that enables using an existing access token (JWT) to bootstrap the SSO session. See [Bootstrapping SSO](/docs/lifecycle/authenticate-users/single-sign-on#bootstrapping-sso) for additional information and examples. ### Request Parameters[#](#request-parameters-1) `client_id`Stringrequired The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. `idp_hint`UUIDoptionalAvailable since 1.19.0 An optional unique Identity Provider Id that can allow you to bypass the FusionAuth login page. Adding this request parameter will cause the FusionAuth login page to be skipped, and instead a `302` will be returned with a `Location` header of the IdP login URL. The end result is functionally equivalent to the end user clicking on the Login with Pied Piper button, or entering their email address when using the IdP configuration with managed domains. `locale`String The [locale](/docs/reference/data-types#locales) to be used to render the login page. This is useful if you already know the user's preferred locale before redirecting the user to FusionAuth. See the [Theme Localization](/docs/customize/look-and-feel/localization) documentation for more information. `login_hint`StringoptionalAvailable since 1.19.0 An optional email address or top level domain that can allow you to bypass the FusionAuth login page when using managed domains. If using managed domains, adding this request parameter will cause the FusionAuth login page to be skipped, and instead a `302` will be returned with a `Location` header of the IdP login URL. The end result is functionally equivalent to the end entering their email address when using the IdP configuration with managed domains. If not using managed domains, providing an email address using this parameter prepopulates the email address in the login page. `max_age`IntegeroptionalAvailable 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](/docs/lifecycle/authenticate-users/oauth/prompt#security-considerations) for implementation details. `nonce`StringoptionalAvailable 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` if requested by the `response_type` parameter. `prompt`StringoptionalAvailable 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](/docs/lifecycle/authenticate-users/oauth/prompt#security-considerations) for implementation details, security considerations, limitations and example usage. `redirect_uri`Stringrequired 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. `response_mode`StringoptionalAvailable 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. `response_type`Stringrequired The requested response type, this value determines which tokens will be returned in the redirect URL. For the Implicit Grant, this value must be set to one of the following values: * `token` - Return an `access_token` * `token id_token` - Return both the `access_token` and the `id_token` * `id_token` - Return an `id_token` The `token` response type is not supported when using OpenID Connect. This means that if you specify the `openid` scope the **token** response type is not allowed. `nonce`StringoptionalAvailable 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` if requested by the `response_type` parameter. `scope`Stringoptional If you are using OpenID Connect, the request must contain this parameter and at minimum it must contain `openid`. These scopes modify the behavior of the endpoint: * `openid` - This scope is used to request an `id_token` be returned in the response `state`Stringoptional The optional state parameter. This is generally used as a Cross Site Request Forgery (CSRF) 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`UUIDrequiredAvailable since 1.8.0 The unique Tenant Id. `user_code`StringoptionalAvailable 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. ### Response[#](#response-1) *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. The user is not logged in, the response will contain an HTML form to collect login credentials. | | 302 | The requested user is already logged in, the request will redirect to the location specified in the `redirect_uri` on the request. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors or errors on the redirect URI. The error responses are covered in the [OAuth Error section](/docs/apis/oauth/oauth-error) of the API documentation. | | 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. | Example HTTP Redirect Response ``` HTTP/1.1 302 Found Location: https://piedpiper.com/callback# access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo &expires_in=3599 &id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo &locale=fr &scope=openid &state=abc123 &token_type=Bearer &userState=Authenticated ``` ### Redirect Parameters[#](#redirect-parameters-1) `access_token`String The OAuth access token as described by [RFC 6749 Section 1.4](https://tools.ietf.org/html/rfc6749#section-1.4). This request parameter will be omitted if an access token was not requested in the **response\_type** request parameter. See the [OAuth Tokens](/docs/lifecycle/authenticate-users/oauth/tokens#access-token) documentation for more information. `expires_in`String The number of seconds the access token will remain active. This request parameter will be omitted if an access token was not requested in the **response\_type** request parameter. `id_token`String The OpenID Id Token. This token is represented as a JSON Web Token (JWT). This request parameter will be omitted if an id token was not requested in the **response\_type** request parameter. See the [OAuth Tokens](/docs/lifecycle/authenticate-users/oauth/tokens#id-token) documentation for more information. `locale`String The [locale](/docs/reference/data-types#locales) that was used 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](/docs/customize/look-and-feel/localization) documentation for more information. `state`String The state that was provided on the Authorization request. This parameter will be omitted if the **state** request parameter was not provided. `token_type`String The token type. The value will be `Bearer` if an access token was requested in the **response\_type** request parameter, this request parameter will otherwise be omitted. `userState`String The FusionAuth user state. 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 has not been verified. * `AuthenticatedRegistrationNotVerified` - The user is successfully authenticated and registered, but the registration has not been verified for the requested application.