Use your custom domain for Stytch assets and API calls
What is a custom domain?
When using a service like Stytch to implement part of your application's functionality, your users's browsers will be making API calls and requesting assets that are handled by Stytch's servers. While it is often workable to have these requests go directly to Stytch, it can be desirable, and sometimes necessary, to configure your application to serve these requests from your own domain.
Why use a custom domain?
Having the URL for components of your application served from your own domain instead of calling out to stytch.com can be a better experience for your users.
In addition, some Stytch products are more directly affected by not using a custom domain. Fraud protection, for instance, is more likely to be blocked by ad blockers. Emails to your users, such as those sent by Magic Links, will appear to come from an stytch.com address instead of your domain. More info on how custom domains interact with our products can be found below.
Setting up a custom domain
Pre-existing implementation
If you have a pre-existing Stytch implementation, using a custom domain will change the shape of some or all of your URLs from Stytch's domain, e.g. api.stytch.com, to your domain.
That means if you have any application business logic, redirect URLs, or SSO Connections that are already set up with Stytch's default domain, you'll need to migrate those to use your custom domain. More detail in Stytch products which use custom domains below.
In order to configure a custom domain, there are two sources which you will need to update:
- Your DNS records will need to be updated with your provider to include a CNAME record. This will create a subdomain on your site which acts as an alias for a subdomain of stytch.com
- Your Stytch configuration will need to be updated to inform Stytch of the details of your subdomain.
It's best to approach this process by doing both steps in parallel.
1Adding a custom domain
Start by going to your Project details in the Stytch dashboard. Scroll down in the Project Settings view until you see the "Custom domain setup" section.
Click the "+ Add New" button to open a dialog with information needed for the next step. Take note of the URL provided, {SUBDOMAIN}.stytch.com, as we will need it for the next step.
2Updating your DNS records
A CNAME record in your domain should be updated to point to this URL.
Stytch custom domains for Live and Test environments cannot use the same subdomain name in their CNAME entries.
The process for this varies by DNS provider, but most providers will have instructions to follow. Here are links to updating the appropriate DNS records for some popular providers:
3Finish configuring Stytch
Finish the configuration process in Stytch by entering your full domain in the final field of the dialog box and clicking "Verify".
DNS records may take up to 48 hours to propagate and be verified, however usually this happens within minutes to hours rather than days. If you are able to verify the existance of your DNS changes exist via a dig on your machine, but they haven't yet been verified with Stytch after about 15 minutes, please reach out to support@stytch.com and we can help troubleshoot.
Stytch products which use custom domains
Custom domains can have a far-reaching impact on how your app interacts with Stytch. These are some of our products which benefit from a custom domain:
HttpOnly Cookies
Stytch's SDKs will make requests to api.stytch.com by default, but HttpOnly cookies cannot be used across domains. To properly use HttpOnly cookies with Stytch's SDKs your app will need to configure a custom domain.
Login emails
Paid feature
Sending emails from your own custom domain is a paid branding feature, see our Pricing page for more details.
If Stytch is not configured with a custom domain, emails sent by Stytch to your users (for instance, when using magic links) will appear to come from a Stytch email address (e.g. login@stytch.com).
Using a custom domain will let you deliver emails from your own domain, which can help with ensuring consistent branding, but it does come with some risks.
Stytch maintains a strong email domain reputation and sends enough emails per month to ensure that email providers, like Gmail and Outlook, land our login emails in your user's inbox quickly and reliably. If you use a custom email domain, you will need ensure that your domain also holds a strong reputation and sends enough email volume, a good rule of thumb is 100,000 login emails per month, so that email providers do not flag your domain as potentially spam.
OAuth
For some OAuth providers (such as Google), the domain used for logging in must be authorized by the provider in order to properly display your app's consent screen. In order for the consent screen to indicate that it is returning to your app instead of to stytch.com, the redirect URI provided to the login flow must be owned by your authorized domain.
Single Sign-On (SSO)
An SSO Connection requires your users to add callback URLs within their Identity Provider (IdP), e.g. acs_url and audience_uri. These URLs, without a custom domain, look like https://api.stytch.com/v1/b2b/sso/callback/saml-connection-live-2925a83e-754c-43ce-b4a7-4957c1f9a14b.
Once you set a custom domain, you'll need to make sure that the domain of those URLs use your chosen domain, e.g. https://<YOUR_SUBDOMAIN>.<YOUR_DOMAIN>.com/v1/b2b/sso/callback/saml-connection-live-2925a83e-754c-43ce-b4a7-4957c1f9a15c.
Note: If you have any pre-existing SSO Connections already set up with your customers, you'll need to reach out to them and have them update those to match.
Fraud protection
Our fraud protection product is more effective in various ways when it is hosted from your own domain. For more detailed information about fraud protection please reach out to support@stytch.com.
Next steps
Visit the Project details section of the Dashboard to set up your custom domain.
For questions, reach out to support@stytch.com.