> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Hosted Backend API | FusionAuth Docs Learn about the APIs that you to perform OAuth2 Authorization Code Flow login, logout, and refresh for applications. # Hosted Backend API [Edit on GitHub](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/docs/apis/hosted-backend.mdx) [View Markdown](https://fusionauth.io/docs/apis/hosted-backend.md) 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](https://fusionauth.io/blog/how-to-authenticate-your-react-app.md#create-the-express-server) 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](https://fusionauth.io/docs/get-started/core-concepts/applications.md#oauth) 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](https://fusionauth.io/articles/oauth/oauth-token-storage.md#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](https://fusionauth.io/docs/operate/deploy/proxy-setup.md). 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](https://github.com/FusionAuth/fusionauth-javascript-sdk-express/tree/main). * Configure a [custom domain name for the FusionAuth Cloud instance](https://fusionauth.io/docs/get-started/run-in-the-cloud/cloud.md#updating-with-existing-custom-domains). 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. ## 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](#callback) endpoint. To use this API, redirect the browser to this route. This is not meant to be called by non-browser clients. ### Request [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) Start the login flow GET/app/login/{clientId}?redirect\_uri={redirectUri}&state={state}&scope={scope} #### Request Parameters `clientId`UUIDrequired The client Id for your Application. `redirect_uri`Stringoptional 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](#callback) as the **redirect\_uri** to `/oauth2/authorize` as that route will handle the token exchange. `state`Stringoptional 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`StringoptionalDefaults 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 ```plaintext 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](https://fusionauth.io/docs/operate/secure/cors.md) 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](#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](#callback) endpoint. If the user is logged in they will be redirected to `/oauth2/authorize` and subsequently to the [Callback](#callback) endpoint. [Self-service Registration](https://fusionauth.io/docs/get-started/core-concepts/applications.md#registration) will need to be enabled otherwise this endpoint will redirect to [Login](#login). To use this API, redirect the browser to this route. This is not meant to be called by non-browser clients. ### Request [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) Start the registration flow GET/app/register/{clientId}?redirect\_uri={redirectUri}&state={state}&scope={scope} #### Request Parameters `clientId`UUIDrequired The client Id for your Application. `redirect_uri`Stringoptional 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](#callback) as the **redirect\_uri** to `/oauth2/register` as that route will handle the token exchange. `state`Stringoptional 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`StringoptionalDefaults 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 ```plaintext 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](https://fusionauth.io/docs/operate/secure/cors.md) 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 [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) 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_id`UUIDrequired The client Id for your Application. `tenantId`UUIDrequired The Id of the Tenant that is associated with the Application. `code`Stringrequired The authorization code. `locale`Stringoptional The [locale](https://fusionauth.io/docs/reference/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/customize/look-and-feel/localization.md) 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. Example Request URL ```plaintext 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.at`String The encoded access token. This cookie is written in the response as a `Secure` `HttpOnly` persistent 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 [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) Refresh the access token POST/app/refresh/{clientId} #### Request Parameters `client_id`UUIDrequired The client Id for your Application. Example Request URL ```plaintext 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.at`String The encoded access token. This cookie is written in the response as a `Secure` `HttpOnly` persistent 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 [!JWT Authentication](https://fusionauth.io/docs/apis/authentication.md#jwt-authentication) Get info about the user GET/app/me/ Example Request URL ```plaintext 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 `applicationId`UUID 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. `birthdate`StringAvailable 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. `email`String 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_verified`Boolean 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_name`StringAvailable 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_name`StringAvailable 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. `name`StringAvailable 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_name`StringAvailable 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_number`StringAvailable 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_verified`BooleanAvailable 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. `picture`StringAvailable 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_username`StringAvailable 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. `roles`Array 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. `sub`UUID The subject of the token. The value is the unique Id of the FusionAuth user. Example JSON Response With Compatibility Scope Handling ```json { "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 ```json { "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](#callback) or [Refresh](#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 [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) Start the logout flow GET/app/logout/{clientId}?redirect\_uri={redirect\_uri} #### Request Parameters `clientId`UUIDrequired The client Id for your Application. `post_logout_redirect_uri`Stringoptional 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 ```plaintext 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. |