Auth Hosting Application

The Descope Auth Hosting App is a standalone React application that hosts and runs your Descope Flows, enabling you to deliver authentication experiences without embedding any Descope SDKs in your own application.

By default, this app is hosted by Descope at https://auth.descope.io, but you can also:

• Configure a Custom Domain to serve the app from your own domain.
• Self-host and customize the app (e.g., change the branding, add a background image, or pass flow inputs).

When to Use Auth Hosting

Auth Hosting is ideal in the following scenarios:

1. You don't have a frontend application

If you're integrating Descope authentication into tools you don't control—such as Freshworks, Docebo, Salesforce, or other SaaS platforms—Auth Hosting gives you a fully managed login and authentication experience without requiring any frontend development.

2. You're using Descope as a federated identity provider (IdP)

When Descope is used as the identity provider with OIDC or SAML, you can configure the Flow Hosting URL to point to any hosted Descope Flow.

• If you do have your own frontend application, you can embed our SDK and set the Flow Hosting URL to point to your own SPA page with the flow.
• But if you don't have an app, or prefer not to embed our SDK, Auth Hosting gives you a hosted alternative to deliver the login experience via redirects—ideal for federated login across multiple services.

3. You're using inbound apps and need to show a consent screen

If you're building an OAuth-based flow where users need to grant access to a third-party application, you often need to display a consent screen. Auth Hosting lets you run this screen as part of a hosted flow—no need to build or host the UI yourself.

For example, if you're protecting MCP servers with Descope and need to show a consent screen as part of the connection flow to an MCP server, Auth Hosting will host the consent flow for you.

4. You're using a no-code/low-code platform like Bubble or Wix

Platforms like Bubble, Wix, or Webflow can sometimes make it complicated to embed custom JavaScript components. Auth Hosting provides a clean solution by hosting the flow externally and redirecting users through a complete authentication experience—without needing to inject anything into the page.

Key Features

• Customizable Flows: Run any Descope flow by specifying the flow query parameter.
• CNAME Configuration: If you've set up a custom domain (available on Pro or higher plans), your Descope project will automatically include an Auth Hosting page served from your custom domain—giving you a branded, fully hosted authentication experience.
• Dynamic Background Color: Optionally, change the app's background color dynamically using the bg query parameter, allowing for a seamless integration into your application's design scheme.
• Flow Inputs: Optionally, be able to pass in specific tenant information using the tenant query parameter, providing a personalized authentication experience for users of specific tenants. Other attributes can be passed in as well, if hosting yourself.

This is an example of what the auth hosting application will look like:

Usage

To use the Auth Hosting App you will need to append your Project ID, which can be found under [Project Settings], to the end of https://auth.descope.io/<YOUR_PROJECT_ID. If you wish to use a custom domain, configure the CNAME under your [Project Settings], and the app will automatically utilize your own custom domain. When deploying or integrating the app, use the following query parameters to customize the authentication experience:

• flow: Specifies which authentication flow to run. Example: ?flow=login.
• bg: Changes the background color. Example: ?bg=ffffff.
• tenant: If your project uses multi-tenancy, specify the tenant. Example: ?tenant=example_tenant.
• debug: Allows you to see more in-depth flow errors in the console.
• style: Allows you to run a specific style for your specific application.
• theme: Allows you to enforce a specific theme for your Flows.

When applications redirect to Descope (as their federated identity provider), they will then be taken to the page you've configured as your Flow Hosting URL.

Therefore, using Descope as an OIDC / SAML provider, such as with Auth.js or with other Applications, you will need to configure the Flow Hosting URL under each app to be https://auth.descope.io/<YOUR_PROJECT_ID?flow=<Your Flow ID>.

Favicon

If you're using the Default OIDC Federated Application in your Descope project, you can customize the favicon shown on your Auth Hosting page.

By default, the Descope favicon is displayed, but you can replace it with your own branding:

To change the icon, click on the pencil icon and upload your image.

This feature allows you to brand your hosted authentication flows more consistently by replacing the default Descope icon with your own.

Styling Per Application

If you're using Federated Applications with Auth Hosting, you can append the style and theme URL parameters in your Flow Hosting URL to adjust the styling of your flows for each application. Learn more about it here

Host the App Yourself

As an alternative option, you can host the app yourself with Vercel or some other hosting service. In the main README, you will find a deploy to Vercel button that can basically deploy a version of this app almost instantaneously in Vercel. You can also clone this repo as a template and deploy with AWS, Netlify, or DigitalOcean.

This is the recommended approach if you want to edit the application in any way that cannot be done with the query parameters above. This includes if you want to input custom values into the flow from your frontend as documented here, or if you want to change the background image of the flow completely and not just the color.

To host the app locally, follow these steps:

1. Clone the app repository. And follow the instructions in the README to install dependencies, set up environment variables, and run the app.
2. Replace the Flow Hosting URL in your Federated Application configuration with http://localhost:3000/<YOUR_PROJECT_ID>?flow=<YOUR_FLOW_ID>.

Your flow should appear automatically when you go to this URL using Descope as a federated identity provider: http://localhost:3000/<YOUR_PROJECT_ID?flow=<YOUR_FLOW_ID>.