Descope Components
Descope Components are components used to render Descope Flows and provide context in your application. This includes the UI elements and logic as defined in your project console.
Before using the Descope Components, make sure to import and initialize the relevant SDK.
Auth Provider
The AuthProvider
is the main component that wraps your application and provides the necessary context for the Descope SDK to work.
Base URL Configuration
Here is an example of configuring the AuthProvider
with a custom domain:
baseUrl
The baseUrl
is the URL (your custom domain, if configured) where all backend/flow requests will go to from your client application. This includes authentication requests, flow interactions, and API calls to Descope services.
When using a custom domain for Descope, you should set this to your custom domain URL instead of the default Descope URLs.
baseStaticUrl
The baseStaticUrl
is specifically for the URL where the SDK will fetch static assets for flow rendering, such as CSS files, images, and other static resources. This is typically your custom domain + "/pages" (e.g., https://auth.yourcompany.com/pages
).
baseCdnUrl
The baseCdnUrl
is the URL of the custom CDN that you can use to host your static assets. This is used if you do not wish to use descopecdn.com
as the default CDN.
Important
Both the baseUrl
and baseStaticUrl
are recommended to be set when using a custom domain, or if you're on a Private Cloud Deployment of Descope.
Cookie Configuration Options
You can choose to store the session token in a cookie instead of localStorage. This is done by passing the sessionTokenViaCookie
prop to the AuthProvider
component.
The Descope SDK will then automatically store the session token on the DS
cookie.
Note
Use this option if session token will stay small (less than 1k). Session token can grow, especially in cases of using authorization, or adding custom claims.
Here are the available cookie configuration options, in the AuthProvider
component:
Option | Type | Description | Default |
---|---|---|---|
sameSite | Strict ,Lax ,None | Controls the cookie's same-site policy. | Strict |
secure | boolean | Specifies whether the cookie is sent over secure (HTTPS) connections. | true |
Here is an example of setting both sameSite
and secure
explicitly:
Example Configuration of AuthProvider (for each SDK)
Now, whenever you call fetch()
, the cookie will automatically be sent with the request. Descope backend SDKs also support extracting the token from the DS cookie.
Note
The session token cookie, by default, is set as a Secure
cookie and therefore will only be sent over HTTPS connections.
In addition, some browsers (e.g. Safari) may not store Secure
cookie if the hosted page is running on an HTTP protocol.
Descope Flow Component
Customize the Descope Flow Component by passing in the following props:
theme
: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"styleId
: style Id can be the id of the style you wish to run your flows withdebug
: debug can be set to true to enable debug moderedirectUrl
: Redirect URL for OAuth and SSO (will be used when redirecting back from the OAuth provider / IdP), or for "Magic Link" and "Enchanted Link" (will be used as a link in the message sent to the the user)redirectAfterSuccess
: Redirect URL after the flow's success.redirectAfterError
: Redirect URL upon error in the flow.autoFocus
: autoFocus can be true, false or "skipFirstScreen". Default is true.- true: automatically focus on the first input of each screen
- false: do not automatically focus on screen's inputs
- "skipFirstScreen": automatically focus on the first input of each screen, except first screen
errorTransformer
: errorTransformer is a function that receives an error object and returns a string. The returned string will be displayed to the user. For more information, refer to Customizing Flow Errors.locale
: locale can be any supported locale which the flow's screen translated to. if not provided, the locale is taken from the browser's locale.logger
: logger is an object describing how to log info, warn and errors.dismissScreenErrorOnInput
: when used, the general error message that appears on screen on user input will be cleared once the form is being re-edited. The value should be set to true.
Note
For information on parameters that can be utilized within your flow (e.g. tenant, screen inputs, etc.), refer to the Flow Inputs Doc.
Triggered Events
onReady
: onReady is an event that is triggered when the flow is ready to be displayed. It's useful for showing a loading indication before the page is ready.onSuccess
: Function that executes when authentication succeeds. User information is returned and accessible with e.detail.user.onError
: Function that executes with authentication fails.
Default Flows
Use default flow components that render the Descope component with a predefined flow ID.
Widgets
Widgets are Descope components that let you delegate operations to your customers. Whether your implementation is tenant-based or not, you can embed these components inside your application to allow your customers to perform various self-service operations.
Customize the widgets by passing in the following props. These customizations can be applied to any of the available widgets:
theme
: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"widgetId
: widgetId is the ID of the widget you wish to use.onLogout
: onLogout is an event that is triggered when the user logs out. It's useful for redirecting the user to the login page.onReady
: onReady is an event that is triggered when the widget is ready to be displayed. It's useful for showing a loading indication before the page is ready.
You can learn more about Widgets and their implementation on the Widgets Overview doc.