Hosted Backend APIs

    Overview

    This API has been available since 1.45.0

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

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

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

    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.

    Login

    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

    URI

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

    Request Parameters

    clientId [UUID] Required

    The client Id for your Application.

    redirect_uri [String] Optional

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

    state [String] Optional

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

    scope [String] Optional defaults 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.

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

    URI

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

    Request Parameters

    clientId [UUID] Required

    The client Id for your Application.

    redirect_uri [String] Optional

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

    state [String] Optional

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

    scope [String] Optional defaults 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.

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

    URI

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

    Request Parameters

    client_id [UUID] Required

    The client Id for your Application.

    tenantId [UUID] Required

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

    code [String] Required

    The authorization code.

    locale [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 [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 [String] Optional

    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.

    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.

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

    The encoded access token. This cookie is written in the response as a Secure HTTPOnly session cookie.

    app.rt [String]

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

    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_exp [String]

    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

    URI

    POST /app/refresh/{clientId}

    Request Parameters

    client_id [UUID] Required

    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.

    Table 5. 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.at [String]

    The encoded access token. This cookie is written in the response as a Secure HTTPOnly session cookie.

    app.rt [String]

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

    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_exp [String]

    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.

    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

    URI

    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.

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

    applicationId [UUID]

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

    birthdate [String]

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

    email [String]

    The email address of the User.

    email_verified [Boolean]

    Indicates if the User’s email has been verified.

    family_name [String]

    The last name of the User if available.

    given_name [String]

    The first name of the User if available.

    name [String]

    The full name of the User if available.

    middle_name [String]

    The middle name of the User if available.

    phone_number [String]

    The phone number of the User if available.

    picture [String]

    A URL to a picture of the User if available.

    preferred_username [String]

    The username of the User if available.

    roles [Array]

    The roles assigned to the User in the authenticated Application.

    sub [UUID]

    The subject of the access token. This value is equal to the User’s unique Id in FusionAuth.

    Example JSON Response
    
{
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "birthdate": "1982-03-10",
  "email": "richard@pipedpuper.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"
}

    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

    URI

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

    Request Parameters

    clientId [UUID] Required

    The client Id for your Application.

    redirect_uri [String] Optional

    The URL encoded URL that the browser will be redirected to at the end of the logout flow. If not provided, this will be the Logout URL configured for the Application. If another value is used, it must be defined in the Authorized Redirect URLs 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.

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

    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.