The JavaScript SDK provides a customizable pre-built login form to start a login flow, along with methods that communicate directly with the Stytch API. These help you get up and running with Stytch faster by avoiding the struggles associated with creating a login UI and removing the need to create endpoints on your backend to make requests to Stytch.
Compatibility and requirements
Languages
The SDK is available in vanilla Javascript along with specialized versions for React and Next.
Browsers
Chrome and Safari on all platforms
Firefox on desktop platforms
TLS 1.2 must be supported by the browser
Supported authentication products
Email magic links
One-time passcodes
OAuth
WebAuthn
TOTPs
Crypto wallets
Session management
User management
Passwords
Biometrics
Installation
Install the @stytch/vanilla-js, @stytch/react packages via npm or yarn.
The JavaScript SDK provides a pre-built UI to trigger Email Magic Links, and methods to send and authenticate magic links that you can connect to your own UI. Use either of these approaches to quickly get up and running with magic links.
Methods
The SDK provides methods that can be used to send magic links and authenticate tokens in the links later.
To call these methods, Email Magic Links must be enabled in the SDK Configuration page of the Stytch dashboard.
Send
The Send method wraps the send Email Magic Link API endpoint. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.
This method is also used when you need to add an email address to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs an email address that does not match one on their Stytch User object, upon successful authentication the new email address will be appended to the emails array. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
email*string
The email of the user to send the invite magic link to.
Configurationobject
Additional configuration.
Collapse
login_magic_link_urlstring
The URL that users click from the login email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.
signup_magic_link_urlstring
The url the user clicks from the sign-up email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.
login_expiration_minutesint
Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
signup_expiration_minutesint
Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
The Login or create method wraps the login_or_create Email Magic Link API endpoint.
Method parameters
email*string
The email of the user to send the invite magic link to.
Configurationobject
Additional configuration.
Collapse
login_magic_link_urlstring
The url the user clicks from the login email magic link. This should be a url that your app receives and parses and subsequently send an API request to authenticate the magic link and log in the user. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.
signup_magic_link_urlstring
The url the user clicks from the sign-up email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and sign-up the user. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.
login_expiration_minutesint
Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
signup_expiration_minutesint
Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
The Authenticate method wraps the authenticate magic link API endpoint which validates the magic link token passed in. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
Method parameters
token*string
The magic link token from the token query parameter in the URL.
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The SDK also comes with a pre-built UI component for our Email Magic Links product. It wraps our login_or_create Email Magic Link API endpoint, which finds an existing user or creates a new user and sends them a magic link via email.
To add Email Magic Links to the login UI, add SDKProductTypes.emailMagicLinks to the products array in the configuration and the appropriate emailMagicLinksOptions.
To see all authentication and customization options, see the UI config section below.
One-time passcodes can be sent via email, phone number, or WhatsApp. One-time passcodes allow for a quick and seamless login experience on their own, or can layer on top of another login product like Email magic links to provide extra security as a multi-factor authentication (MFA) method.
Methods
To call these methods, One-time passcodes must be enabled in the SDK Configuration page of the Stytch dashboard.
Login Or Create via SMS
Wraps Stytch's login_or_create via SMS API endpoint. Call this method to send an SMS passcode to new or existing users.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
Wraps Stytch's send via SMS API endpoint. Call this method to send an SMS passcode to existing users.
This method is also used when you need to add a phone number to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs a phone number that does not match one on their Stytch User object, upon successful authentication the new phone number will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
Wraps Stytch's login_or_create via email API endpoint. Call this method to send an email passcode to new or existing users.
Method parameters
email*string
The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Sign-up.
Wraps Stytch's send via email API endpoint. Call this method to send an email passcode to existing users.
This method is also used when you need to add an email address to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs an email address that does not match one on their Stytch User object, upon successful authentication the new email address will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
email*string
The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Sign-up.
Wraps Stytch's login_or_create via WhatsApp API endpoint. Call this method to send a WhatsApp passcode to new or existing users.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
Wraps Stytch's send via WhatsApp API endpoint. Call this method to send a WhatsApp passcode to existing users.
This method is also used when you need to add a phone number to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs a phone number that does not match one on their Stytch User object, upon successful authentication the new phone number will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
The authenticate method wraps the authenticate one-time passcode API method which validates the code passed in. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
Method parameters
method_id*string
The email_id or phone_id where the OTP was delivered. This value will be returned in the associated /login_or_create or /send response.
code*string
The code to authenticate.
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The SDK also comes with a pre-built UI component for our One-time passcode product. It uses the methods mentioned above to send passcodes to users and authenticate the passcodes they enter.
To add One-time passcodes to the login UI, add SDKProductTypes.otp to the products array in the configuration.
To see all authentication and customization options, see the UI config section below.
OAuth is a popular authentication framework that delegates authentication to an external identity provider
(often shortened to IdP) like Google, Facebook, Apple, and Microsoft. A user relies on their membership from
that provider to sign in instead of creating another password, and developers can enrich their users'
experiences with the information shared by the providers.
The JavaScript SDK provides a pre-built UI for OAuth flows, as well as methods to start and authenticate OAuth flows that you can connect to your own UI. Use either of these approaches to quickly get up and running with OAuth.
Methods
The SDK provides methods that can be used to get the URL to start an OAuth flow and authenticate tokens in the links later.
To call these methods, OAuth must be enabled in the SDK Configuration page of the Stytch dashboard.
start
The oauth.$provider.start() methods start OAuth flows by redirecting the browser to one of Stytch's oauth start endpoints. The method will also generate a PKCE code_verifier and store it in local storage on the device (See the PKCE OAuth guide for details). If your application is configured to use a custom subdomain with Stytch, it will be used automatically.
oauth.amazon.start()
oauth.apple.start()
oauth.bitbucket.start()
oauth.coinbase.start()
oauth.discord.start()
oauth.facebook.start()
oauth.github.start()
oauth.gitlab.start()
oauth.google.start()
oauth.linkedin.start()
oauth.microsoft.start()
oauth.slack.start()
oauth.twitch.start()
Method parameters
Configurationobject
Additional configuration.
Collapse
login_redirect_urlstring
The URL Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.
The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.
signup_redirect_urlstring
The URL Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.
The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.
custom_scopesstring
An optional list of custom scopes that you'd like to request from the user in addition to the ones Stytch requests by default.
The authenticate method wraps the authenticate OAuth API endpoint which validates the OAuth token passed in. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
Method parameters
token*string
The OAuth token from the token query parameter in the URL.
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
Our Javascript SDK wraps our start OAuth endpoint which kicks off the OAuth flow for your users. You'll want to set up each OAuth provider in your Dashboard before using it in the SDK. The SDK supports Google, Google One Tap, Amazon, Apple, Bitbucket, Coinbase, Discord, GitHub, GitLab, Facebook, LinkedIn, Microsoft, Slack, and Twitch OAuth.
To add OAuth to the login UI, add SDKProductTypes.oauth to the products array in the configuration and the appropriate oauthOptions.
To see all authentication and customization options, see the UI config section below.
The Web Authentication API (WebAuthn) is a specification that allows web applications on supported browsers to authenticate a user via
authenticator types such as built-in device biometrics (e.g. facial recognition on mobile and
fingerprint readers on desktop) or secure hardware keys (e.g. YubiKeys). While WebAuthn has many benefits,
developers need to understand the API to implement it securely. Stytch's WebAuthn product simplifies the
process by abstracting the implementation details of WebAuthn for developers to make it as quick as
possible to implement securely.
Methods
The Stytch SDK can be used to create new WebAuthn registrations for users and authenticate existing WebAuthn registrations.
To call these methods, WebAuthn must be enabled in the SDK Configuration page of the Stytch dashboard.
Register
Wraps Stytch's register_start and register WebAuthn endpoints and the navigator.credentials web API. Call this method to prompt the user to enroll a new WebAuthn factor and save the factor in Stytch.
Call webauthn.register inside an event callback triggered by a user gesture.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook if you are using React.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Method parameters
domainstring
The domain for the WebAuthn registration. Defaults to window.location.hostname.
authenticator_typestring
The requested authenticator type of the WebAuthn device. The two valid value are platform and cross-platform. If no value passed, we assume both values are allowed.
Wraps Stytch's authenticate_start and authenticate WebAuthn endpoints and the navigator.credentials web API. Call this method to prompt the user to authenticate an existing WebAuthn registration. In order to use this method, the user must have already logged in with a primary Stytch authentication factor (such as OAuth, OTPs, Passwords, or Magic Links). If this method succeeds, the WebAuthn credential will be added to the user's existing session as an authentication_factor.
Call webauthn.authenticate inside an event callback triggered by a user gesture.
If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
Method parameters
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
domainstring
The domain for the WebAuthn authentication. Defaults to window.location.hostname
Time-based One-time Passcodes (TOTPs) are one-time passcodes that are generated based on a shared secret and the current time.
TOTPs are also often referred to as Authenticator Apps and are a common form of secondary authentication.
Creating a Stytch instance of a TOTP for a User creates a shared secret. This secret is shared by Stytch
with the end user's authenticator application of choice (e.g. Google Authenticator).
The authenticator app can then generate TOTPs that are valid for a specific amount of time (generally 30 seconds).
The end user inputs the TOTP and the developer can use the authenticate method to verify that the TOTP is valid.
Methods
The Stytch SDK can be used to generate new TOTP secrets for users, and authenticate existing TOTP secrets.
To call these methods, TOTPs must be enabled in the SDK Configuration page of the Stytch dashboard.
Create
Wraps Stytch's create endpoint. Call this method to create a new TOTP instance for a user. The user can use the authenticator application of their choice to scan the QR code or enter the secret.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook if you are using React.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
expiration_minutesint
The expiration for the TOTP instance. If the newly created TOTP is not authenticated within this time frame the TOTP will be unusable. Defaults to 60 (1 hour) with a minimum of 5 and a maximum of 1440.
Wraps Stytch's authenticate endpoint. Call this method to authenticate a TOTP code entered by a user.
If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
totp_code*string
The TOTP code to authenticate. The TOTP code should consist of 6 digits.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
Wraps Stytch's recovery_codes endpoint. Call this method to retrieve the recovery codes for a TOTP instance tied to a user.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook if you are using React.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Wraps Stytch's recover endpoint. Call this method to authenticate a recovery code for a TOTP instance.
If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
recovery_code*string
The recovery code to authenticate.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
Crypto wallets allow users to hold digital assets, like cryptocurrencies and NFTs, and easily cryptographically authenticate themselves on a blockchain.
Methods
The SDK provides methods that can be used to authenticate a user via their crypto wallet.
To call these methods, Crypto Wallets must be enabled in the SDK configuration page of the Stytch dashboard.
Authenticate start
Wraps Stytch's Crypto Wallet Authenticate Start endpoint. Call this method to prompt the user to sign a challenge using their crypto wallet.
Load the challenge data by calling cryptoWallets.authenticateStart().
You'll then pass this challenge to the user's wallet for signing, you can pass this challenge by using the crypto provider's built-in API and by including the crypto_wallet_address and challenge that is provided from cryptoWallets.authenticateStart(). See Ethereum's EIP-1193 for an example of Ethereum's provider API.
Method parameters
crypto_wallet_type*string
The type of wallet to authenticate. Currently ethereum and solana are supported. Wallets for any EVM-compatible chains (such as Polygon or BSC) are also supported and are grouped under the ethereum type.
crypto_wallet_address*string
The crypto wallet address to authenticate.
Example
React
import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';
export const Login = () => {
const stytchClient = useStytch();
const trigger = useCallback(async () => {
/* Request user's address */
const [crypto_wallet_address] = await ethereum.request({
method: 'eth_requestAccounts',
});
/* Ask Stytch to generate a challenge for the user */
const { challenge } = await stytchClient.cryptoWallets.authenticateStart({
crypto_wallet_address,
crypto_wallet_type: 'ethereum',
});
/* Ask the user to sign the challenge, this takes place on your frontend and uses the browser's built-in crypto provider API. */
const signature = await ethereum.request({
method: 'personal_sign',
params: [challenge, crypto_wallet_address],
});
/* Send the signature back to Stytch for validation */
/* await stytchClient.cryptoWallets.authenticate({
crypto_wallet_address,
crypto_wallet_type: 'ethereum',
signature,
session_duration_minutes: 60,
});
}, [stytchClient]); */
return (
<button onClick={trigger}>
Sign in with Ethereum
</button>
);
};
RESPONSE
200
{
"challenge": "Signing in with Project: 7_EPetPqfdEiDCJtgad6-xsXytN3Ee9tx6mdRTQK3fC7-J2PDxpP1GAvYB9Ic4E09h-K88STiRIzKSGP",
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
"status_code": 200
}
Authenticate
Wraps Stytch's Crypto Wallet Authenticate endpoint. Call this method after the user has been prompted to sign the challenge with their wallet in cryptoWallets.authenticateStart().
If this method succeeds and the user is not already logged in, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser. If the user is already logged in, the crypto wallet will be added to the user.crypto_wallets[] array and associated with user's existing session as an authentication_factor.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession() hook if you are using React.
Method parameters
crypto_wallet_type*string
The type of wallet to authenticate. Currently ethereum and solana are supported. Wallets for any EVM-compatible chains (such as Polygon or BSC) are also supported and are grouped under the ethereum type.
crypto_wallet_address*string
The crypto wallet address to authenticate.
signature*string
The signature from the message challenge.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
Example
React
import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';
export const Login = () => {
const stytchClient = useStytch();
const trigger = useCallback(async () => {
/* Request user's address */
/* const [crypto_wallet_address] = await ethereum.request({
method: 'eth_requestAccounts',
}); */
/* Ask Stytch to generate a challenge for the user */
/* const { challenge } = await stytchClient.cryptoWallets.authenticateStart({
crypto_wallet_address,
crypto_wallet_type: 'ethereum',
}); */
/* Ask the user to sign the challenge, this takes place on your frontend and uses the browser's built-in crypto provider API. */
/* const signature = await ethereum.request({
method: 'personal_sign',
params: [challenge, crypto_wallet_address],
}); */
/* Send the signature back to Stytch for validation */
await stytchClient.cryptoWallets.authenticate({
crypto_wallet_address,
crypto_wallet_type: 'ethereum',
signature,
session_duration_minutes: 60,
});
}, [stytchClient]);
return (
<button onClick={trigger}>
Sign in with Ethereum
</button>
);
};
The SDK also comes with a pre-built UI component for our Crypto wallets product. It wraps our authenticate_start and authenticate Crypto wallet API endpoints, which finds an existing user or creates a new user and authenticates them with their wallet.
To add Crypto wallets to the login UI, add SDKProductTypes.crypto to the products array in the configuration.
To see all authentication and customization options, see the UI config section below.
Stytch supports creating, storing, and authenticating password based users, as well as support for account recovery (password reset) and account deduplication with passwordless login methods.
Methods
The SDK provides methods that can be used to create and authenticate password based users.
To call these methods, Passwords must be enabled in the SDK Configuration page of the Stytch dashboard.
Create
The send method wraps the create Password API endpoint.
email*string
The email of the new user.
password*string
The password for the new user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The authenticate method wraps the authenticate Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
email*string
The email of the user.
password*string
The password of the user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The resetByEmailStart method wraps the reset_by_email_start Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
email*string
The email of the user that requested the password reset.
Configurationobject
Additional configuration.
Collapse
reset_password_redirect_urlstring
The url that the user clicks from the password reset email to finish the reset password flow. This should be a url that your app receives and parses before showing your app's reset password page. After the user submits a new password to your app, it should send an API request to complete the password reset process. If this value is not passed, the default reset password redirect URL that you set in your Dashboard is used. If you have not set a default reset password redirect URL, an error is returned.
login_redirect_urlstring
The url that the user clicks from the password reset email to skip resetting their password and directly login. This should be a url that your app receives, parses, and subsequently sends an API request to the magic link authenticate endpoint to complete the login process without reseting their password. If this value is not passed, the login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.,
reset_password_expiration_minutesint
Set the expiration for the password reset, in minutes. By default, it expires in 30 minutes. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
reset_password_template_idstring
Use a custom template for password reset emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Passwords - Password reset.
The resetByEmail method wraps the reset_by_email Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
token*string
The token to authenticate.
password*string
The new password for the user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The resetByExistingPassword method wraps the reset_by_existing_password Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The resetBySession method wraps the reset_by_session Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.
password*string
The new password for the user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
This method allows you to check whether or not the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password. All passwords must pass the strength requirements to be accepted as valid.
The strengthCheck method wraps the strength_check Password API endpoint.
password*string
The password to strength check.
emailstring
The email associated with the password. If the email address is included, it will be factored into strength evaluation via our password breach checks. If you do not include the email, it is possible that the strength check response will evaluate as valid – but the password will fail with a weak_password error when used in the Create password endpoint due to a breach check failure.
Once a user has successfully logged in, the SDK can be used to view and manage that user's information, add additional authentication factors, or delete factors that are no longer used.
Methods
To call these methods, Manage user data must be enabled in the SDK Configuration page of the Stytch dashboard.
Get user
The SDK provides two methods for getting a user. The recommended approach is to use the synchronous method, user.getSync, and listen to changes with the user.onChange method.
If logged in, the user.getSync method returns the cached user object. Otherwise it returns null. This method does not refresh the user's data. The stytch-react library provides the useStytchUser hook that implements these methods for you to easily access the user and listen for changes.
The user.onChange method takes in a callback that gets called whenever the user object changes. It returns an unsubscribe method for you to call when you no longer want to listen for such changes.
The asyncronous method, user.get, wraps the get user endpoint. It fetches the user's data and refreshes the cached object if changes are detected. The Stytch SDK will invoke this method automatically in the background, so you probably won't need to call this method directly.
Example
React
import React from 'react';
import { useStytchUser } from '@stytch/react';
export const Home = () => {
const { user } = useStytchUser();
return user ? (
<p>Welcome, {user.name.first_name}</p>
) : (
<p>Log in to continue!</p>
);
};
Update user
Wraps Stytch's update user endpoint. Use this method to change the user's name, untrusted metadata, and attributes.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook if you are using React.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Method parameters
nameobject
The name of the user. If at least one name field is passed, all name fields will be updated.
Collapse
first_namestring
The first name of the user. Replaces an existing first name, if it exists.
middle_namestring
The middle name(s) of the user. Replaces an existing middle name, if it exists.
last_namestring
The last name of the user. Replaces an existing last name, if it exists.
untrusted_metadataobject
The untrusted_metadata field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and cannot be used to store critical information. See the Metadata reference for complete field behavior details.
Wraps Stytch's delete authentication factors family of endpoints and can be used to remove factors from a user.
These methods cannot be used to remove all factors from a user. A user must have at least one email, phone number, or OAuth provider associated with their account at all times, otherwise they will not be able to log in again.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook if you are using React.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Method parameters
method_id*string
ID of the email, phone number, or WebAuthn registeration to be deleted.
The SDK may be used to check whether a user has a cached session, view the current session, refresh the session, and revoke the session. To authenticate a session on your backend, you must use either the Stytch API or a Stytch Backend SDK.
Methods
Get session
The SDK provides the session.getSync method to retrieve the current session. The session.onChange method can be used to listen to session changes.
If logged in, the session.getSync method returns the cached session object. Otherwise it returns null. The stytch-react library provides the useStytchSession hook that implements these methods for you to easily access the session and listen for changes.
The session.onChange method takes in a callback that gets called whenever the user object changes. It returns an unsubscribe method for you to call when you no longer want to listen for such changes.
Wraps Stytch's authenticate Session endpoint and validates that the session issued to the user is still valid. The SDK will invoke this method automatically in the background. You probably won't need to call this method directly. It's recommended to use session.getSync and session.onChange instead.
Method parameters
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The config object for login or signup functionality.
Collapse
products*array
The products array allows you to specify the authentication methods that you would like to expose to your users.
The order of the products that you include here will also be the order in which they appear in the login form, with the first product specified appearing at the top of the login form.
Currently the JavaScript SDK supports our emailMagicLinksoauth, crypto and otp products.
emailMagicLinksOptions*object
The options for email magic links. This is required if emailMagicLinksis present in the products array.
Collapse
loginRedirectURL*string
The URL that will appear in your email template and accepts a token (ex: you implement 'https://example.com/authenticate?token=123' in your app and pass 'https://example.com/authenticate' as the redirect URL). This link should route to an endpoint that authenticates your user via Stytch's authenticate magic link endpoint and redirect to your app's experience for existing users.
loginExpirationMinutesint
Number of minutes the magic link is valid for.
signupRedirectURL*string
The URL that will appear in your email template and accepts a token (ex: you implement 'https://example.com/authenticate?token=123' in your app and pass 'https://example.com/authenticate' as the redirect URL). This link should route to an endpoint that authenticates your user via Stytch's authenticate magic link endpoint and redirect to your app's experience for new users.
signupExpirationMinutesint
Number of minutes the magic link is valid for.
loginTemplateIdstring
Custom template ID for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
signupTemplateIdstring
Custom template ID for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
createUserAsPendingboolean
This flag determines whether the status of a new user will be pending. Users are created with an active status by default. If this flag true, users will be saved with a pending status in Stytch's backend. An example usage of this would be to invite users.
oauthOptions*object
The options for OAuth. This is required if oauth is present in the products array.
Collapse
providers*Array<Provider>
An array of OAuth providers you wish to use. Each Provider is an object with a type key that determines the type of provider. Each Provider accepts an optional custom_scopes array of scopes that Stytch will request for your application in addition to the base set of scopes required for login. The order of the providers in the array determines the order of the rendered buttons.
Collapse
Googleobject
Adds the Google OAuth login button and Google One Tap. If you enable one_tap you must also provide a position parameter; embedded will display Google One Tap within the existing JavaScript SDK login form alongside the other configured sign-in options, floating will display the One Tap prompt in the top right corner.
If Google OAuth is the only authentication option specified and one_tap is set to floating, the normal Google OAuth login button will not appear in the SDK login form and only the floating One Tap box will be displayed.
Note: If you enable Google One Tap, ensure that you've added your app or website's URL as an authorized JavaScript origin in your Google Developer dashboard. If you're using localhost, make sure to add both http://localhost and http://localhost:port (e.g http://localhost:3000). See Step 5 in your Google OAuth setup guide here. Note: Google One Tap cannot be used to authorize additional custom scopes.
// with One Tap
{ type: 'google', one_tap: true, position: 'embedded' | 'floating' }
// with standard OAuth
{ type: 'google', custom_scopes?: ['...'] }
Microsoftobject
Adds the Microsoft OAuth start button.
{ type: 'microsoft', custom_scopes?: ['...'] }
Appleobject
Adds the Apple OAuth start button. Apple has no additional scopes that may be requested at this time.
{ type: 'apple' }
GitHubobject
Adds the GitHub OAuth start button.
{ type: 'github', custom_scopes?: ['...'] }
Gitlabobject
Adds the Gitlab OAuth start button.
{ type: 'gitlab', custom_scopes?: ['...'] }
Facebookobject
Adds the Facebook OAuth start button.
{ type: 'facebook', custom_scopes?: ['...'] }
Slackobject
Adds the Slack OAuth start button.
{ type: 'slack', custom_scopes?: ['...'] }
Discordobject
Adds the Discord OAuth start button.
{ type: 'discord', custom_scopes?: ['...'] }
Amazonobject
Adds the Amazon OAuth start button.
{ type: 'amazon', custom_scopes?: ['...'] }
Bitbucketobject
Adds the Bitbucket OAuth start button.
{ type: 'bitbucket', custom_scopes?: ['...'] }
Coinbaseobject
Adds the Coinbase OAuth start button.
{ type: 'coinbase', custom_scopes?: ['...'] }
LinkedInobject
Adds the LinkedIn OAuth start button.
{ type: 'linkedin', custom_scopes?: ['...'] }
Twitchobject
Adds the Twitch OAuth start button.
{ type: 'twitch', custom_scopes?: ['...'] }
loginRedirectURLstring
The URL that your users will redirect to after completing the OAuth authentication flow at a given OAuth provider, i.e. after the user returns from authenticating via Google.
This URL should route to an endpoint within your app that will complete the Stytch OAuth authentication flow, by hitting our oauth/authenticate endpoint.
If not specified, the user will be redirected to the default login redirect URL that you've configured in your Dashboard.
signupRedirectURLstring
The URL that your users will redirect to after completing the OAuth authentication flow at a given OAuth provider, i.e. after the user returns from authenticating via Google.
This URL should route to an endpoint within your app that will complete the Stytch OAuth authentication flow, by hitting our oauth/authenticate endpoint.
If not specified, the user will be redirected to the default sign up redirect URL that you've configured in your Dashboard.
otpOptionsobject
The options for one time passcodes. This is required if otpis present in the products array.
Collapse
methods*array
The methods array allows you to specify the authentication methods that you would like to expose to
your users. The order of the products that you include here will also be the order in which they appear
in the login form, with the first product specified appearing at the top of the login form. We currently
support passcodes on email, sms and whatsapp
expirationMinutesint
Number of minutes the passcode is valid for.
loginTemplateIdstring
(Email OTP only) Custom template ID for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.
signupTemplateIdstring
(Email OTP only) Custom template ID for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Sign-up.
sessionOptionsobject
The options for session management. If you are using the otp or cryptoproduct, we also create a session for users when they log in.You can access a user or session using the User or Session SDK methods.products array.
Collapse
sessionDurationMinutesint
Set the session lifetime to be this many minutes from now; minimum of 5 and a maximum of 525600 minutes (365 days). Note that a successful authentication will continue to extend the session this many minutes.
passwordOptions*object
The options for passwords. This is required if passwordsis present in the products array.
Collapse
loginRedirectURL*string
The redirect URL used in your password reset email template for users which opt to log in with a magic link opposed to resetting their password. This link should route to an endpoint that authenticates your user via Stytch's authenticate magic link endpoint and redirect to your app's experience for existing users.
loginExpirationMinutesint
Number of minutes the magic link is valid for.
resetPasswordRedirectURL*string
The redirect URL used in your password reset email template for users who opt to reset their password. This link should route to an page that lets your user reset their password via Stytch's reset password endpoint.
resetPasswordExpirationMinutesint
Number of minutes the reset password token is valid for.
resetPasswordTemplateIdstring
Custom template ID for password reset emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Passwords - Password reset.
stylesobject
The style object allows you to customize the look of the SDK. You can specify some of them or none at all. We'll use our defaults for the ones you don't specify. Check out the UI customization options in the SDK here.
Collapse
fontFamilystring
The font family that will apply to all text in the SDK.
hideHeaderTextboolean
When this value is false, the title and description text will not show in the SDK.
containerobject
The configuration object for the Stytch UI container.
Collapse
widthstring
The width of the SDK container.
backgroundColorstring
The background color of the SDK container.
borderColorstring
The border color of the SDK container.
borderRadiusstring
The border radius of the SDK container.
colorsobject
The configuration object for colors used in the Stytch UI components.
Collapse
primarystring
Your primary brand color. This will be applied to most of the text in the SDK.
secondarystring
Your secondary brand color. This will be applied to text disclaimers and other visual elements.
successstring
A success color to be used in visual elements.
errorstring
An error color to be used in visual elements.
buttonsobject
The configuration object for buttons in the Stytch UI component.
Collapse
primaryobject
The configuration object for primary buttons
Collapse
textColorstring
The text color of the primary button.
backgroundColorstring
The background color of the primary button.
borderColorstring
The border color of the primary button.
borderRadiusstring
The border radius of the primary button.
secondaryobject
The configuration object for secondary buttons
Collapse
textColorstring
The text color of the secondary button.
backgroundColorstring
The background color of the secondary button.
borderColorstring
The border color of the secondary button.
borderRadiusstring
The border radius of the secondary button.
logoobject
The configuration object for your custom logo.
Collapse
logoImageUrlstring
The URL of your custom logo. The image will be resized to fit a max width of 50px, and a max width of 100px.
callbacksobject
Optional callbacks that are triggered by various events in the SDK. See more details about the callbacks here.
Collapse
onEvent(data) => void
A callback function that responds to events sent from the SDK.
onError(data) => void
A callback function that responds to errors in the SDK. It is useful for debugging during development and error handling in production.
CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a security measure
that attempts to verify that a user is human and not a malicious bot. This helps protect your application against
spammy sign ups and other automated bot attacks. Set up CAPTCHA in your Dashboard via our step by step guide and the SDK will protect every login according to your configured threshold. Only Google
Enterprise is currently supported, but please contact us if there is a CAPTCHA provider you would like to see supported in the future!
Hiding the reCAPTCHA Badge
When Google Enterprise reCAPTHCA is configured, Google automatically displays a badge in the lower corner of the screen. This badge may be hidden with CSS as long as you include the reCAPTCHA branding visibly in the user flow. See Google's documentation for more details.
.grecaptcha-badge { visibility: hidden; }
If you are using the React SDK with Next.js, the following utility component can be used to programmatically hide the badge on a page by page basis.
Callbacks are optional functions for the JavaScript SDK that allow you to do things like take actions in your app or send logs to your backend based on where your user is in the flow.
onEvent
A function that is called when the stytch client makes a request. The function expects an argument of an event object, the event object has type and data objects.
A function that is called when an error occurs. The function expects an argument of an StytchError object, the StytchError object has a message property.
// Example of an API related error.
"message": "StytchSDKAPIError: [401] unauthorized_credentials Unauthorized credentials. See https://stytch.com/docs/api/errors/401 for more information. request_id: request-id-test-8e2a9758-713e-49a2-8b62-f9169bbabded",
// Example of a network related error.
"message": "SDKAPIUnreachableError: Failed to send magic link Unable to contact the Stytch servers. Are you online?"
// Example of a schema related error.
"message": "StytchSDKSchemaError: [400] Request does not match expected schema. email: should be string"
// Example of an error with using our SDK.
"message": "StytchSDKUsageError: Invalid call to <METHOD_NAME>"
Cookies & session management
Stytch will automatically save the user's Session in two cookies:
stytch_session that will contain the opaque session token returned from the API
stytch_session_jwt that will contain the session JWT returned from the API
For example, if you load the SDK on https://app.mycoolsite.com it will set
Note: If you load the SDK on localhost, we will not mark the cookie as secure.
Authenticating sessions on your backend
Since the session is stored in the site's cookies, the browser will include these cookies in the request headers to your backend if they share a domain. For any protected requests, your backend should validate either the stytch_session or stytch_session_jwt before processing with the request. The session may be validated using any Backend SDK.
Validating the opaque session in Node.js / Express.
In certain cases you may need to manually override the Stytch Session managed by the frontend SDK with a Session available on your backend. A common reason would be when adding custom claims to a Session which is an action that can only be done server-side.
In order to override the SDK managed Session you will need to overwrite the the stytch_session and stytch_session_jwt browser cookies. This can be done by setting the cookies in the response headers from your backend, or by setting the values directly on document.cookie. Be sure to use the same cookie names and properties which are normally set by the SDK.
In most cases, the SDK will automatically detect the new values, and proceed as normal. However, if the SDK is not properly reacting to the updated Session you can force the SDK to refresh the session.
// Call session authentication without any parameters to refresh the session in the SDK
stytchClient.session.authenticate();
Stytch Client Options
The Stytch Client can be configured by passing in an optional object as the second parameter. This currently lets developers configure options related to the cookies set by Stytch's SDK.
Stytch automatically saves the user's session in two cookies: stytch_session that will contain the opaque session token returned from the API and stytch_session_jwtthat will contain the session JWT returned from the API.
{
"cookieOptions": {
/**
* The name of the cookie containing the opaque Stytch session token.
* Defaults to `stytch_session`
*/
"opaqueTokenCookieName": "string",
/**
* The name of the cookie containing the opaque Stytch session token.
* Defaults to `stytch_session_jwt`
*/
"jwtCookieName": "string",
/**
* What HTTP paths the cookies should be available on.
* Equal to configuring the `;path=${}` param in the set-cookie directive.
* Defaults to unset.
*/
"path": "string",
/**
* Whether to make the cookies available to subdomains.
* When true, equivalent to configuring the `;domain=${window.location.host}` directive
* When false, equivalent to leaving the directive unset
* Defaults to true.
*/
"availableToSubdomains": "boolean",
}
}
Migration Guide
If you are currently using the @stytch/stytch-js or @stytch/stytch-react SDKs, please upgrade to our newest SDK using the guides below.
Version 0.5.0 introduces an updated styles object used to customize the appearance of the SDK UI. This change introduces many new styling options, and restructures how existing styles are defined.
width is now container.width
primaryColor is now buttons.primary.backgroundColor
primaryTextColor is now colors.primary
secondaryTextColor is now colors.secondary
Note: that we have also added new buttons.secondary properties which you can check out here.
Values lightGrey and darkGrey do not have direct replacements. Check out all of the new properties we've added here.
Review this pull request to see what migrating our example app from 0.4 to 0.5 looked like.
Migrating to v0.10
Version 0.10.0 of @stytch/vanilla-js introduces our JavaScript SDKs for B2B. Check out in-depth docs for them here
In this version, the default value of availableToSubdomains in StytchClientOptions is now false
SWR & caching
On first load, many websites must make a network request to determine whether a user is logged in before the site can start rendering the user interface. This slows down users' ability to interact with the application and ultimately leaves them with a sluggish experience.
Stytch JavaScript SDK embraces stale-while-revalidate (SWR) - a caching and data fetching strategy that promises faster time-to-interactivity and snappier UX. While SWR is most closely associated with React, the principles can apply to any web application.
Here's how it works:
The page first loads. Stytch's SDK checks cached data to determine if a user has logged in previously on the same device, and returns that data to your app immediately.
Stytch's SDK refreshes the user's data in the background while your app starts.
Your app makes requests to your backend to pull in application-specific data. Your backend validates the session stored in the request's cookies, and then completes the request.
In the rare case that the user's session has been terminated from another device, your backend will fail the request and return a 401 error. The Stytch SDK will also notify your app that the session is no longer valid through the useStytchUser and useStytchSession hooks or HOCs.
If a SWR approach isn't right for you, you can explicitly call stytch.user.get() to refresh the user object with a network call, and/or stytch.session.authenticate() to make sure the user is still logged in.
User privacy measures
To guard against potential misuse of the client-side library by bad actors, the SDK has a few restrictions:
No user data is shared with the browser until the user has logged in
The client may only access data for one user at a time - endpoints like search users are not available
Certain endpoints, such as update user, require step-up or multi-factor authentication in order to be used
To prevent account enumeration, login or create endpoints for one-time passcodes and magic links do not return the user_id as they would when using the direct API
The JavaScript SDK is not a complete replacement for the Stytch API - they are designed to be used together in order to create secure and low-friction login experiences. Some processes must necessarily happen on your server rather than client (for example, validating a session_token).
Multi-factor authentication
The Stytch SDK allows users to edit the verification mechanisms associated with their account (adding an email, deleting a phone number, adding a second factor method, etc.).
In order to access these routes, we require the that the user be authenticated with a secure combination of factors.
Stytch factors are split into three general groups based on what they prove:
Access to another online account or email address (OAuth, email magic links, email passcodes, and embeddable magic links)
Access to a phone number (SMS and WhatsApp passcodes)
Access to a dedicated 2nd factor (WebAuthn and TOTP)
In order for a session to be considered secure, it must include factors from at least two categories. For example, if a user completes a successful Email magic link flow and a successful SMS passcode flow, they will be considered securely authenticated. A user that completes an Email magic link flow + an OAuth flow with their Google account will not. In addition, at least one factor in the session must be less than an hour old.
Important: If a user does not have enough registered factors, they will always be allowed to add one.