/
Contact usSee pricingStart building

    Management

    API keys
    Redirect urls
    Event logs
    Dashboard roles & permissions
    Webhooks

    Programmatic Workspace Actions

    Overview
    Limits
    Email templates
      Email template object
      Sender information object
      Prebuilt customization object
      Custom HTML customization object
      Create email template
      Get email template
      Get all email templates
      Update email template
      Delete email template
    Projects
      Project object
      Create project
      Get project
      Get all projects
      Update project
      Delete project
    Project metrics
      Metrics object
      Get project metrics
    JWT templates
      JWT template object
      Get JWT templates
      Set JWT templates
    Password strength config
      Password strength config object
      Get password strength config
      Set password strength config
    Public tokens
      Public token object
      Create public token
      Get all public tokens
      Delete public tokens
    RBAC policy
      Policy object
      Role object
      Permission object
      Resource object
      Get RBAC policy
      Set RBAC policy
    Redirect URLs
      Redirect URL object
      URL type object
      Create redirect URL
      Get redirect URL
      Get all redirect URLs
      Update redirect URL
      Delete redirect URL
    SDK config
      SMSAutofillMetadata object
      ConsumerSDKBasicConfig object
      ConsumerSDKSessionsConfig object
      ConsumerSDKMagicLinksConfig object
      ConsumerSDKOTPsConfig object
      ConsumerSDKOAuthConfig object
      ConsumerSDKTOTPsConfig object
      ConsumerSDKWebauthnConfig object
      ConsumerSDKCryptoWalletsConfig object
      ConsumerSDKDFPPAConfig object
      ConsumerSDKBiometricsConfig object
      ConsumerSDPasswordsConfig object
      ConsumerConfig object
      B2BSDKBasicConfig object
      B2BSDKSessionsConfig object
      B2BSDKMagicLinksConfig object
      B2BSDKOTPsConfig object
      B2BSDKOAuthConfig object
      B2BSDKTOTPsConfig object
      B2BSDKSSOConfig object
      B2BSDKPasswordsConfig object
      B2BConfig object
      Get Consumer SDK config
      Set Consumer SDK config
      Get B2B SDK config
      Set B2B SDK config
    Secrets
      Secret object
      CreatedSecret object
      Create secret
      Get secret
      Get all secrets
      Delete secret
Get support on SlackVisit our developer forum

Contact us

Home

/

Workspace management

/

Management

/

Redirect urls

Redirect URLs

Redirect URLs are used by several Stytch products including Email Magic Links, OAuth, and Passwords (as part of the reset flow). There are four types of redirect urls: login, sign-up, invite, and reset password. These values are set in your code during the associated API call, and tell Stytch where to redirect users upon successful completion of the authentication flow.

By default, all redirect URLs are set to http://localhost:3000/authenticate for the Test environment.

Structure

Redirect URL structure

Redirect URLs for traditional web applications contain seven parts. Values 1-3 and 7 are set by you and values 4, 5, and 6 are set by Stytch. If you are using mobile or desktop deep links, values 1 and 2 will be different, e.g. slack://auth/callback.

  1. Protocol: e.g. https:// or http://.

  2. Domain: e.g. example.com. www.example.com and example.com are considered equivalent.

  3. Path: This route is where your backend will accept the redirect and authenticate the user, e.g. /authenticate.

  4. Public token: For our Passwords product, your public_token is included in the redirect URL to allow our JavaScript SDK, if you use it, to complete the authentication flow.

  5. Stytch token type: The stytch_token_type query parameter indicates which product and authentication flow the user is currently completing. You'll use this value to call the appropriate Authenticate endpoint. For example, a value of stytch_token_type=magic_links indicates that you'll need to call the Magic Links Authenticate endpoint with the token to complete the authentication flow.

    Possible values are in our Consumer API are:

    • magic_links: Used by our Email Magic Links product.
    • oauth: Used by our OAuth product.
    • reset_password: Used by our Passwords product during the reset password flow.
    • login: Used by our Passwords product during the reset flow as the alternative one click login.

    Possible values in our B2B API are:

    • multi_tenant_magic_links: Used by our Email Magic Links product.
    • multi_tenant_passwords: Used by our Passwords product.
    • sso: Used by our SSO product.
    • discovery: Used for Magic Link Discovery flows.
    • discovery_oauth: Used for OAuth Discovery flows.
    • oauth: Used by our OAuth product.
  6. Token: The token value that you'll pass to the appropriate Authenticate endpoint, e.g. token=rM_kw42CWBhsHLF62V75jELMbvJ87njMe3tFVj7Qupu7.

  7. Query parameters: You may set any arbitrary query parameters and include state data within the redirect URL. See the Query parameters section below, e.g.?next_route=profile.

Example redirect URLs

// Magic Links redirect URL example
"https://example.com/authenticate?stytch_token_type=magic_links&token=rM_kw42CWBhsHLF62V75jELMbvJ87njMe3tFVj7Qupu7"

// Passwords redirect URL examples
// This URL powers the "Reset Password" button in password reset emails:
"http://example.com/authenticate?stytch_token_type=reset_password&token=H3qsCWufbGf4u2hOPKgIaScT_ao2yC4yPAD24zug1KjW"

// This URL powers the "Log in without a password" button in password reset emails:
"https://example.com/v1/magic_links/redirect?public_token=public-token-test-03abfdeb-5c39-48db-898b-9a2c42a09e0f&stytch_token_type=login&token=RGLT-fxUSgOdWLmPxQX5ScTxg5buOYba2YsgdJL0E5Tg"

// OAuth redirect URL example
"http://example.com/login?stytch_token_type=oauth&token=pYIfdlODeuQOjf1CULw8LcF3roDeSy0J81AQznWOMK8o"

Security

For security, a redirect URL must be added in the Dashboard before being used. This prevents bad actors from creating a fake login portal, phishing your users, and redirecting them to a site they control. In the Dashboard, you may set a default redirect URL for each type which allows you to omit setting it as a param when making the associated API call. Redirect URLs are not shared across the Test and Live environments, and must be added to each individually.

Testing

To make testing and development easier, you may use local, non-HTTPS, addresses (e.g. http://localhost:3000) in the Test environment. All Live redirect URLs must use HTTPS.

In the Test environment, you may also use * to specify a wildcard for the domain. For example, https://*.stytch.com. Query parameters cannot contain wildcards and must be an exact match.

This can be helpful in generating preview environments (e.g. https://myapp-*.vercel.app). NOTE https://*.vercel.app is not a valid redirect URL, as vercel.app is listed as a public suffix. Allowing wildcards with public suffixes introduces a potential security concern. A bad actor could spoof your subdomain if the environment is hosted on a shared third party service (e.g. https://badactor.vercel.com). This domain would resolve as valid if you are using the wildcard subdomain example in the Dashboard.

Query parameters

Redirect URLs can optionally include query parameters. Query parameters can be useful as an alternative way to persist state outside of browser cookies and local storage during authentication.

URLs must be an exact match. If you have an optional query parameter optional_param, create two redirect URLs: https://www.example.com and https://www.example.com?optional_param={}.

User app state example

An Ecommerce app may want to persist a user’s shopping cart and other app state in their URL so they can serve the user a tailored checkout experience post-login, e.g. https://www.example.com/signup?cart_id=123&promo_banner=true.

Query parameters can be defined as part of the redirect URL in the Dashboard using the pattern param_name={}. In the example above, the developer would need to set the following redirect URL in the Dashboard, https://www.example.com/signup?cart_id={}&promo_banner={}.

Returning to current page example

Another common use case for query parameters is storing the current route location of a user before they authenticate. That way, after a user logs in, your application can parse this value from the query parameters, and redirect the user to the same page that they were on before authenticating.

  1. Add a redirect URL like https://www.example.com/authenticate?next_route={} in the Dashboard.
  2. When starting an authentication flow that features a redirect, grab the current page path, and pass the full redirect URL as a parameter in your call to Stytch (e.g. https://www.example.com/authenticate?next_route=/profile/details/)
  3. After redirecting to https://www.example.com/authenticate and successfully authenticating, finally redirect your user to the path stored in next_route (e.g. https://www.example.com/profile/details/).

Warning! Be sure to validate the next_route contents before doing the final redirect in order to prevent open redirect vulnerabilities.

Native redirect URLs

Native redirect URLs for desktop and mobile applications — for example slack://auth/callback — are also supported.

If you are using Email Magic Links or Passwords along with native redirect URLs you may need to make additional configuration changes. Review Magic link redirect URL routing for more information.

Structure

Example redirect URLs

Security

Testing

Query parameters

User app state example

Returning to current page example

Native redirect URLs