Hosted Backend

Overview

This API has been available since 1.45.0

The hosted backend APIs provide a pre-built solution for getting your app up and running using the OAuth2 Authorization Code grant with PKCE. We have in the past shown you how to create these endpoints yourself but this solution allows you to get going with your app without writing any backend code. You just need FusionAuth!

Prerequisites

Be sure to review the Applications section of the FusionAuth user guide to ensure proper configuration before using the hosted endpoints.

The hosted backend endpoints will set the following cookies, which are Secure and have a SameSite value of Lax. This follows our expert advice on client-side storage.

When you are making requests against these endpoints from your JavaScript application, ensure that you are sending cookies as well. The exact syntax varies, but for many frameworks, you must set withCredentials to true when you make the request.

Cookies Set By the Hosted Backend

Name	HttpOnly	Description
app.at	true	The access token for the configured application. This is a JWT and can be presented to your APIs to access data and functionality.
app.rt	true	The refresh token for the configured application. Only present if the `offline_access` scope is requested. This can be presented to FusionAuth to retrieve a new access token.
app.idt	false	The Id token for the user for the configured application. Only present if the `openid` scope is requested. This is a JWT and can be accessed by JavaScript to display user account information.
app.at_exp	false	The UNIX epoch timestamp indicating when the access token will expire. This can be checked by JavaScript to determine when a refresh token should be used to get a new access token.

FusionAuth will set the domain on these cookies to .example.com where example is the domain name that FusionAuth is serving from either from the domain or any subdomain, com is the top-level domain, and the . allows the cookie to match the domain and all subdomains. If the host is a simple host name or IP address FusionAuth will set the domain to that (i.e. localhost or 127.0.0.1). If FusionAuth is on a nested domain, then it will set cookies on the broadest domain that is not a top-level domain.

What this means is that FusionAuth needs to be hosted on the same domain or a subdomain or sibling domain of the application that you intend to use with these endpoints.

When developing against a FusionAuth Cloud instance with a hostname ending in fusionauth.io, unless your application shares the same domain of fusionauth.io attempts to use these endpoints will fail with a 403 status code.

These endpoints do not work correctly for cross origin requests. Cross origin requests occur when the application making the request to FusionAuth is using a separate domain. For example, if your application URL is app.acme.com and the FusionAuth URL is acme.fusionauth.io requests from your application to FusionAuth will be considered cross origin.

If possible, have FusionAuth and your application served by the same domain, using a proxy if needed. For example, serve your app from app.acme.com and FusionAuth from auth.acme.com.

If this configuration is not possible, use one of these alternative methods:

Develop using a local FusionAuth instance, so both your webapp and FusionAuth are running on localhost.
Do not use the FusionAuth hosted backend, and instead write your own backend with a cross origin cookie policy: here’s an example.
Configure a custom domain name for the FusionAuth Cloud instance.

Modifying FusionAuth CORS configuration options does not fix this issue because the cookies that FusionAuth writes will not be accessible cross domain.

For example if your app is on app.example.com and FusionAuth is on auth.example.com the cookies would be usable by your application. If FusionAuth is on auth.department.division.example.com and the app lives on app.otherdepartment.otherdivision.example.com, the cookies would still be usable, since the cookies are set on the example.com domain.

This API will start an OAuth2 Authorization Code grant by building a valid request and then redirecting the browser to our /oauth2/authorize endpoint. If the user is not logged in the user will be presented with the login page and prompted for credentials before being redirected back to the Callback endpoint.

To use this API, redirect the browser to this route. This is not meant to be called by non-browser clients.

Request

Start the login flow

GET /app/login/{clientId}?redirect_uri={redirectUri}&state={state}&scope={scope}

Request Parameters

clientIdUUIDrequired

The client Id for your Application.

redirect_uriString

The URL encoded URL that the browser will be redirected to at the end of the login flow. If provided, this URL must be included in the Authorized Redirect URLs array for your application. If not provided, the default will be the first value in the Authorized Redirect URLs array configured for your application. This parameter is validated the same as if it were being passed to /oauth2/authorize, however when using this endpoint FusionAuth will pass Callback as the redirect_uri to /oauth2/authorize as that route will handle the token exchange.

stateString

The value of this parameter will be echoed back in the state parameter of the redirect URL at the end of the login flow.

scopeStringDefaults to openid offline_access

The OAuth2 scope parameter to be passed to the /oauth2/authorize endpoint. The format is a URL encoded, space-separated list of scopes (i.e openid+offline_access or openid%20offline_access).

Available scopes:

openid - This scope is used to request the app.idt Id token cookie be returned in the response
offline_access - This scope is used to request the app.rt refresh token cookie be returned in the response

Example Request URL

https://auth.example.com/app/login/297ca84b-69a9-4508-8649-97644e1d0b3d?redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&state=yourStateData&scope=offline_access

Response

Successful invocations of this route will return a 302 redirect to /oauth2/authorize. Other status codes indicate an error.

Response Codes

Code	Description
200	There was an error. The route will serve up an error page with HTML and details on what went wrong.
302	A successful request will redirect the user to `/oauth2/authorize` to log in.
403	A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your CORS Configuration as an Allowed Origin .
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Register

This API will start a registration flow by building a valid request and then redirecting the browser to our /oauth2/register endpoint. This endpoint is nearly identical to the Login endpoint; however the end result is user registration instead of a login. If the user is not logged in the user will be presented with the registration page and prompted for credentials before being redirected back to the Callback endpoint. If the user is logged in they will be redirected to /oauth2/authorize and subsequently to the Callback endpoint.

Self-service Registration will need to be enabled otherwise this endpoint will redirect to Login.

To use this API, redirect the browser to this route. This is not meant to be called by non-browser clients.

Request

Start the registration flow

GET /app/register/{clientId}?redirect_uri={redirectUri}&state={state}&scope={scope}

Request Parameters

clientIdUUIDrequired

The client Id for your Application.

redirect_uriString

The URL encoded URL that the browser will be redirected to at the end of the registration. If provided, this URL must be included in the Authorized Redirect URLs array for your application. If not provided, the default will be the first value in the Authorized Redirect URLs array configured for your application. This parameter is validated the same as if it were being passed to /oauth2/register, however when using this endpoint FusionAuth will pass Callback as the redirect_uri to /oauth2/register as that route will handle the token exchange.

stateString

The value of this parameter will be echoed back in the state parameter of the redirect URL at the end of the registration flow.

scopeStringDefaults to openid offline_access

The OAuth2 scope parameter to be passed to the /oauth2/register endpoint. The format is a URL encoded, space-separated list of scopes (i.e openid+offline_access or openid%20offline_access).

Available scopes:

openid - This scope is used to request the app.idt Id token cookie be returned in the response
offine_access - This scope is used to request the app.rt refresh token cookie be returned in the response

Example Request URL

https://auth.example.com/app/register/297ca84b-69a9-4508-8649-97644e1d0b3d?redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&state=yourStateData&scope=offline_access

Response

Successful invocations of this route will return a 302 redirect to /oauth2/register. Other status codes indicate an error.

Response Codes

Code	Description
200	There was an error. The route will serve up an error page with HTML and details on what went wrong.
302	A successful request will redirect the user to `/oauth2/register` to register.
403	A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your CORS Configuration as an Allowed Origin .
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Callback

You do not need to call this endpoint directly. The browser will be redirected here automatically after a successful login or registration. This is the route that handles the token exchange and sets the cookies on the browser and will redirect the browser to the defined redirect_uri.

This endpoint is documented for educational purposes only.

Request

Receive the callback from the authorization flow

GET /app/callback?code={code}&locale={locale}&state={state}&userState={userState}&client_id={client_id}&tenantId={tenantId}

Request Parameters

client_idUUIDrequired

The client Id for your Application.

tenantIdUUIDrequired

The Id of the Tenant that is associated with the Application.

codeStringrequired

The authorization code.

localeString

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.

stateString

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

userStateString

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.

Example Request URL

https://auth.example.com/app/callback?code=wJfjafZLvo_KH5-D4r-3YwMmStN3yHoZDGmBivjioz0&locale=en&state=eyJjIjoiODVhMDM4NjctZGNjZi00ODgyLWFkZGUtMWE3&userState=Authenticated&client_id=297ca84b-69a9-4508-8649-97644e1d0b3d&tenantId=e707be45-afa8-4881-9efb-4be7288395d2

Response

A successful response will set cookies and return a 302 redirect to the redirect_uri specified in the initial request. Other status codes indicate an error.

Response Codes

Code	Description
200	There was an error. The route will serve up an error page with HTML and details on what went wrong.
302	A successful request will redirect the user to `redirect_uri` specified in the request or the default Authorized Redirect URL configured for the Application.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Cookies

app.atString

The encoded access token. This cookie is written in the response as a Secure HttpOnly persistent cookie.

app.rtString

The refresh token. This cookie is written in the response as a Secure HttpOnly persistent cookie. The cookie expiration is configured in the JWT configuration for the application or the global JWT configuration.

app.idtString

The Id token for the user for the configured application. Only present if the openid scope is requested. This is a JWT and is a Secure persistent cookie that can be accessed by JavaScript to display user account information.

app.at_expString

The unix epoch timestamp indicating when the access token will expire. This is a Secure persistent cookie that can be checked by JavaScript to determine when a refresh token should be used to get a new access token.

Refresh

This endpoint will extract the app.rt cookie if present and use it to make a refresh_token request from /oauth/token. The configuration rules for your Application configuration apply; ensure that Refresh token grant is enabled. If successful a new set of cookies will be set on the response that will continue to allow access to the application. You can call this any time or you can review the value of app.at_exp and call it when the access token is about to expire.

This API request is made from the client application. The browser must NOT be redirected to this endpoint.

Request

Refresh the access token

POST /app/refresh/{clientId}

Request Parameters

client_idUUIDrequired

The client Id for your Application.

Example Request URL

https://auth.example.com/app/refresh/297ca84b-69a9-4508-8649-97644e1d0b3d

Response

A successful response will set cookies and return a 200.

Response Codes

Code	Description
200	There was an error. The route will serve up an error page with HTML and details on what went wrong.
400	The request was not successful. The client needs to reauthorize. Redirect the browser to the `Login` endpoint.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Cookies

app.atString

The encoded access token. This cookie is written in the response as a Secure HttpOnly persistent cookie.

app.rtString

app.idtString

app.at_expString

Me

This API is used to retrieve information about the currently logged in user. This call will take the app.at cookie value and use that to call the /oauth2/userinfo API.

This is an API request made from the client application and the browser must NOT be redirected to this endpoint.

Request

Get info about the user

GET /app/me/

Example Request URL

https://auth.example.com/app/me

Response

A successful response will set cookies and return a 302 redirect to the redirect_uri specified in the initial request. Other status codes indicate an error.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
401	The user is not authorized. Call `Refresh` or redirect the browser to the `Login` endpoint.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body

applicationIdUUID

The unique Id of the Application for which the user has been authenticated.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is not populated.

birthdateStringAvailable since 1.1.0

The birthDate of the User if available. Format will be in YYYY-MM-DD as defined by the OpenID Connect core specification.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

emailString

The email address of the User.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the email scope.

email_verifiedBoolean

The verification status of the email . This value is true when the email is verified.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the email scope.

family_nameStringAvailable since 1.1.0

The last name of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

given_nameStringAvailable since 1.1.0

The first name of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

nameStringAvailable since 1.1.0

The full name of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

middle_nameStringAvailable since 1.1.0

The middle name of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

phone_numberStringAvailable since 1.1.0

The phone number of the user if available. user.phoneNumber or user.mobilePhone will be used in this order of precedence.

When the Scope handling policy is Strict, this field is only populated when the provided token contains the phone scope.

phone_number_verifiedBooleanAvailable since 1.59.0

The verification status of the phone_number . This value is true when the phone number is verified.

This field is only populated when the Scope handling policy is Strict, and the scope claim contains the phone scope.

pictureStringAvailable since 1.1.0

A URL to a picture of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

preferred_usernameStringAvailable since 1.1.0

The username of the user if available.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is only populated when the provided token contains the profile scope.

rolesArray

The roles assigned to the user in the authenticated Application.

In version 1.50.0 and later, when the Scope handling policy is Strict, this field is not populated.

subUUID

The subject of the token. The value is the unique Id of the FusionAuth user.

Example JSON Response With Compatibility Scope Handling

{
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "birthdate": "1982-03-10",
  "email": "richard@piedpiper.com",
  "email_verified": true,
  "family_name": "Hendricks",
  "given_name": "Richard",
  "phone_number": "555-555-5555",
  "picture": "http://www.piedpiper.com/app/themes/pied-piper/dist/images/photo-richard.png",
  "roles": [
    "admin"
  ],
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}

Example JSON Response With Strict Scope Handling And The profile, email And phone Scopes In The Token

{
  "birthdate": "1982-03-10",
  "email": "richard@pipedpiper.com",
  "email_verified": true,
  "family_name": "Hendricks",
  "given_name": "Richard",
  "phone_number": "+15555551212",
  "phone_number_verified": true,
  "picture": "http://www.piedpiper.com/app/themes/pied-piper/dist/images/photo-richard.png",
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}

Logout

This API will start a logout. The cookies set on Callback or Refresh will be removed. If an SSO session was started, it will be ended.

To use this API, redirect the browser to this route and the router will respond with a 302 redirect status code. This is not meant to be called by non-browser clients.

Request

Start the logout flow

GET /app/logout/{clientId}?redirect_uri={redirect_uri}

Request Parameters

clientIdUUIDrequired

The client Id for your Application.

post_logout_redirect_uriString

The URL encoded URL that the browser will be redirected to at the end of the logout flow. This value must be in the Application’s Authorized Redirect URLs list. If no post_logout_redirect_uri is provided, the user will be redirected to the Logout URL configured for the Application.

Example Request URL

https://auth.example.com/app/logout/297ca84b-69a9-4508-8649-97644e1d0b3d?redirect_uri=https%3A%2F%2Fapp.example.com%2

Response

Successful invocations of this route will return a 302 redirect to /oauth2/logout. Other status codes indicate an error. After logout the browser is redirected to the defined redirect_uri.

Response Codes

Code	Description
200	There was an error. The route will serve up an error page with HTML and details on what went wrong.
302	A successful request will redirect the user to `/oauth2/logout` to complete the logout.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Results

Recent

Hosted Backend

Overview

Prerequisites

Request

Request Parameters

Response

Register

Request

Request Parameters

Response

Callback

Request

Request Parameters

Response

Response Cookies

Refresh

Request

Request Parameters

Response

Response Cookies

Me

Request

Response

Response Body

Logout

Request

Request Parameters

Response

Results

Recent