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

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.