Welcome to the Docs
Our products allow you to build frictionless, secure, and engaging authentication flows. Choose one of our SDKs and build your login flow in minutes, or go with our Direct API that offers maximum flexibility.
Overview
Our flexible SDK, your brand
Our SDKs offer flexible templates that can be tailored to your colors, fonts, and logo, so you can easily create seamless onboarding and authentication experiences that delight users and complement your brand—without the trouble of building UI from the ground up.
Maximum customization, minimal hassle
Our Direct API integration considers both developer and user experience to ensure fast, safe, and easy authentication flows. We make integration quick and painless, with clear and comprehensive documentation.
Product suite
Example apps
Learn more about how Stytch works and get up and running quickly using an example app.
Starting with a template
Examples using the Stytch frontend SDKs, for web and mobile. Includes Email Magic Links and all of our OAuth providers, including Google One Tap!
Building from scratch
Examples using the direct API integrating Stytch solely on the back end.
Guides
Step-by-step guides to quickly get up and running with Stytch.
Setting up a new auth solution with the Stytch API
Managing user login with Stytch enables you to authenticate users on an ongoing basis via one-click, passwordless login. When a user signs up for your app, you'll add them to Stytch. Then, whenever a user goes to login to your app, authenticate them via a magic link.
Step 1: Build a sign up or login view
If you don't already have one, you'll need to build a sign up or login view for your app. You can collect any information you want, but you'll need to include an email field so the user can login with their email later.
Step 2: Create a route for authentication
Create a route that will act as your magic link endpoint. Users will be directed there from the login email. The route should accept a token as a query parameter that you will use to authenticate. For example, your route should be something like https://example.com/authenticate. Users will be directed to https://example.com/authenticate?token=abc, where abc is the token you'll pass to our authentication endpoint.
Step 3: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 4: Send a magic link to log in or create a Stytch user
Send either a login or create magic link to the user based on if the email is associated with a user already. If the user was created, use the user_id returned in the response to manage that user within Stytch. Save this user_id with your user's record in your app's storage.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/login_or_create \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"login_magic_link_url": "https://example.com/authenticate",
"signup_magic_link_url": "https://example.com/authenticate"
}'Step 5: Logging in a user: authenticating a token
Once the user clicks the magic link from the email and is directed to either the login_magic_link_url or signup_magic_link_url, you'll use the token from the url to call the authenticate endpoint to log the user in. You'll need to manage the user session from your app. Make sure to replace the token in the url with the actual token.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Step 6: Going live
Request your Live API keys in the dashboard and store them somewhere safe. We suggest using environment variables for your projectID and secret to keep them secure. Then, update the URL you’re using from https://test.stytch.com to https://api.stytch.com
Setting up a new auth solution with the Stytch SDK
Preferred frontend language
This is an integration guide for setting up the Stytch SDK in your app. First, you'll configure our frontend SDK in your client code to create a login experience in your app. Then, you'll add support to your server code for authenticating Stytch magic links. If you have any questions, check out the docs for the SDK or our example app that uses the code in this guide.
Step 1: Gather information
1.1 API Keys
To get started, you’ll need a project ID, secret, and public token that you can find in the API keys tab of the dashboard. You have both test and live credentials for your project. Test your integration using your test API keys. Once you’ve verified your integration, upgrade to your live API keys.
Step 2: Use Stytch.js
2.1 Include Stytch.js
Include the stytch.js script on each of your HTML views that implement login or sign-up. For information about asynchronous and deferred loading of the SDK, please see the reference.
<script id="js-stytch" src="https://js.stytch.com/stytch.js"></script>Add an HTML element where the Stytch Magic Link will mount to. You can use any CSS Selector.
<div id="stytch-sdk"></div>2.2 Initialize the Stytch object
Initialize the Stytch object in Javascript using your test public token (update to live public token once you've tested your integration) and a config object with callbacks. This might be in a <script> tag in your HTML view. Make sure it's below your element that you added in step 2.1.
Configuration:
- onEvent: A callback function that responds to events sent from the SDK. For now, this includes a USER_EVENT_TYPE.
- onSuccess: A callback function that responds to successfully sending a magic link.
- onError: A callback function that responds to errors in the SDK. It is useful for debugging during development and error handling in production.
// Initialize stytch with public token
var STYTCH_PUBLIC_TOKEN = "PUBLIC TOKEN";
var stytch = Stytch(STYTCH_PUBLIC_TOKEN, {
onEvent: async (response) => {
// TODO: check whether the user exists in your DB
const userExists = false;
if (response.data.type === 'USER_EVENT_TYPE' && !userExists) {
try {
await fetch('/users', {
method: 'POST',
mode: 'cors',
body: JSON.stringify({ userId: response.data.userID }),
headers: {
'Content-Type': 'application/json'
},
});
} catch(e) {
console.log(e);
}
}
},
onSuccess: (response) => {
// Handle successfully sent magic link
console.log(response);
},
onError: (response) => {
// Handle an error
console.log(response);
}
});
2.3 Customize Stytch.js
Customize the style and functionality of the SDK. The style object allows you to modify the look and feel to match your app. The config object updates what the magic link will be in the email your users receive (you'll need to implement the magic link endpoint in your app - see step 6). Check out the UI customization options in the SDK here.
// Check out the style options in the docs
var style = {
fontFamily: '"Helvetica New", Helvetica, sans-serif',
primaryColor: '#106ee9',
primaryTextColor: "#090909",
};
var loginOrSignupView = {
products: ['emailMagicLinks'],
emailMagicLinksOptions: {
loginRedirectURL: "https://example.com/authenticate",
loginExpirationMinutes:30,
signupRedirectURL: "https://example.com/authenticate",
signupExpirationMinutes: 30,
};2.4 Add redirect URLs to the Stytch dashboard
2.5 Mount Stytch.js
Finally, mount Stytch to your HTML element using the CSS selector. Make sure your mount function is in a script tag below the HTML element so stytch can mount to it.
stytch.mount({
elementId: "#stytch-sdk",
style: style,
loginOrSignupView: loginOrSignupView
});Step 3: Add server side support to your app for Stytch
Stytch works best with support from your app's server. You'll need to create or modify a few endpoints. The Node examples use express to create http endpoints and express-session for sessions, but they can be replaced with any other http framework.
3.1 Install Stytch
Install the stytch package via npm or yarn. The stytch package provides backend support for the Stytch API.
npm install stytch --save3.2 Create a user
POST/PUT user endpoint: When a user logs in to your app for the first time, the SDK will create a Stytch user for them and return a userId. We recommend adding a stytchUserId field to your user to save it.
app.post('/users', function (req, res) {
var stytchUserId = req.body.userId;
// TODO: Save stytchUserId with your user record in your app's storage
res.send(`Created user with stytchUserId: ${stytchUserId}`);
});3.3 Authenticate a user: GET route
GET authentication endpoint: When a user enters their email and clicks the login button, we will send them an email with a magic link to log in. You need to create a route for the magic link. There are a few ways to do this:
- - Implement a GET route on your frontend that accepts a token and passes it to a route on your backend that passes the token to Stytch to authenticate. This is recommended if your frontend lives separately from your backend.
- - Implement a GET route in your backend that accepts a token and passes it to Stytch to authenticate. This is recommended if your backend and frontend live in the same service.
3.4 Authenticate a user: POST route
POST to Stytch: If your url in the previous step was https://example.com, your user will be directed to https://example.com?token={token} when they click the magic link in the email. You'll pass this token to Stytch to authenticate it. If authentication is successful, create a user session and log them into your app. If you'd like to keep this user logged-in for a while, include "session_duration_minutes": 60 (an hour, for example). Check out the session management guide to learn how to handle the session.
const stytch = require('stytch');
const client = new stytch.Client({
project_id: "PROJECT ID",
secret: "SECRET",
env: stytch.envs.test
});
app.get('/authenticate', function (req, res) {
var token = req.query.token;
client.magicLinks.authenticate(token)
.then(response => {
req.session.authenticated = true;
req.session.save(function(err) {
console.log(err);
});
res.redirect('/home')
})
.catch(error => {
console.log(error);
res.send('There was an error authenticating the user.');
});
});Replacing your password reset flow
Integrate Stytch as a replacement for your forgot password flow. This will be used to complement your existing login methods. To replace your login flow with Stytch, see the Augmenting existing auth flow guide.
Step 1: Create a password reset UI
Here’s an example of a password reset component.
Step 2: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 3: Create user
To send a login email, the user who forgot their password needs to be created with Stytch. Check if the user has a Stytch user ID. If they do not, create a Stytch user for them and save the user ID from the response. This needs to happen once for each user who forgets their password. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID.
curl --request POST \
--url https://test.stytch.com/v1/users \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com"
}'Step 4: Send magic link
When the user wants to reset their password, send a request to send an email magic link. Either the login_magic_link_url or signup_magic_link_url request parameter is the URL the user will be redirected to from the email. The signup_magic_link_url will be used if the user is in a pending state due to using CreateUser's create_user_as_pending request parameter.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/send \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"login_magic_link_url": "https://example.com/login",
"signup_magic_link_url": "https://example.com/signup"
}'Step 5: Authenticate magic link
When the user opens the email, they are prompted to log in by clicking either the login_magic_link_url or signup_magic_link_url from the SendMagicLinkByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, you have successfully verified ownership of the user's email address. That authentication event allows you to provide the user with access to their logged-in profile. While it's not necessary from an authentication perspective at this point, you may also allow them to rotate their password if that's their preference.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Inviting users
Integrate Stytch to easily invite and authenticate users. When a user invites someone to their team, you'll send them a magic link invite with Stytch. The invited user will have a pending status until they click the link to authenticate. At this point, they will become an active user and you can log them in. For an example of how to build this, see our example app.
Step 1: Build an invite user UI
If you don't already have one, you'll need to build an invite user view for your app.
Step 2: Add redirect URLs to the Stytch dashboard
Add the invite URL to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 3: Invite user
When you want to send an invitation to a user, send a InviteByEmail request. The user will receive an email explaining they’ve been invited. This will create a Stytch user with an invited status. Remember to save the user ID from the response. The invite_magic_link_url request parameter is the URL the user will be redirected to from the email.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/invite \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"invite_magic_link_url": "https://example.com/authenticate"
}'Step 4: Authenticate magic link
When the user opens the email, they are prompted to log in for the first time by clicking the provided invite_magic_link_url from the InviteByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. The user’s status will be set to active as well. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Step 5: Later authentication
After the user has accepted their invitation, you can send a magic link to authenticate a user by sending a SendMagic request.
Augmenting existing auth flow
Integrate Stytch email magic links into your existing login flow. It’s easy to replace your existing login flow entirely or add an alternative login method alongside your existing options.
Step 1: Update your login UI
Here’s an example of a login component when Stytch is the only login method.
Step 2: Create user
Since each user needs to be created with Stytch, check if the user logging in or signing up has a Stytch user ID. If they do not, create a Stytch user for them and save the user ID from the response. This needs to happen once per user. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID.
curl --request POST \
--url https://test.stytch.com/v1/users \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com"
}'Step 3: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 4: Send magic link
When a user wants to login using Stytch, send a request to send an email magic link. If a user is signing up for the first time, you can send this request after receiving the user ID from the CreateUser response. Either the login_magic_link_url or signup_magic_link_url request parameter is the URL the user will be redirected to from the email. The signup_magic_link_url will be used if the user is in a pending state due to using CreateUser's create_user_as_pending request parameter.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/send \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"login_magic_link_url": "https://example.com/login",
"signup_magic_link_url": "https://example.com/signup"
}'Step 5: Authenticate magic link
When the user opens the email, they are prompted to log in by clicking either the login_magic_link_url or signup_magic_link_url from the SendMagicLinkByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Setting up a new auth solution with SMS
Integrate Stytch one-time passcodes as your authentication solution.
Step 1: Build your UI for SMS login
Here’s an example of an authentication flow. One screen accepts the user’s phone number and the other accepts their one-time passcode.
Step 2: Login or create user
The LoginOrCreateUserBySMS endpoint will be used to log in or sign up a user. This request will send a one-time passcode to the provided phone number. By default, the code will expire in 2 minutes. You can alter the expiration with the ExpirationMinutes request field. If the phone number isn’t associated with a user yet, a user will be created. If the user_created attribute in the response is true, save the user ID and phone ID from the response. We recommend saving these IDs in new columns of your users table or within a new table linking your users with their Stytch IDs.
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/login_or_create \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'Step 3: Authenticate one-time passcode
The AuthenticateOTP endpoint will be used in conjunction with all LoginOrCreateUserBySMS requests. The user should be prompted to enter the one-time passcode sent to them via SMS. After the user enters their code, send an AuthenticateOTP request with the code along with the phone ID used. If the response is a 200, the user is verified and can be logged in. If you'd like to keep this user logged-in for a while, include "session_duration_minutes": 60 (an hour, for example). Check out the session management guide to learn how to handle the session.
curl --request POST \
--url https://test.stytch.com/v1/otps/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"code": "123456"
}'Add multi-factor authentication (MFA) with SMS
Integrate Stytch one-time passcodes (OTP) as your multi-factor authentication solution.
Step 1: Build your UI for multi-factor authentication
Here’s an example of a multi-factor authentication flow. One screen accepts the user’s phone number and the other accepts their one-time passcode.
Step 2: Create or update user
The user you want to authenticate needs to be a Stytch user with an associated phone number. If they are, continue to Step 3. If the user already has a Stytch ID, send a UpdateUser request to add a phone number. If they don’t, send a CreateUser request to create a user with a phone number. We recommend saving the user and phone IDs in new columns of your users table or within a new table linking your users with their Stytch IDs.
curl --request POST \
--url https://test.stytch.com/v1/users \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'Step 3: Send one-time passcode
Now that the phone number is associated with a Stytch user, send a SendOTPBySMS request. This will send a one-time passcode to the provided phone number. By default, the code will expire in 2 minutes. You can alter the expiration with the ExpirationMinutes request field.
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/send \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'Step 4: Authenticate one-time passcode
The AuthenticateOTP endpoint will be used in conjunction with all SendOTPBySMS requests. The user should be prompted to enter the one-time passcode sent to them via SMS. After the user enters their code, send a AuthenticateOTP request with the code along with the phone ID used. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/otps/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"code": "123456"
}'Integrate Google OAuth via the API
Integrate Google OAuth into your existing login flow. The first three steps involve setting up a Google Cloud Project to get OAuth Credentials. Skip those steps if you already have your Google OAuth credentials.
Step 1: Setup Google Project
Before you can use the Stytch Google OAuth flow, you need to enter a Google OAuth client ID and client secret into the Stytch dashboard. Google requires you to create a Google Cloud project to get a client ID and client secret. Please follow the steps here to create one.
Step 2: Setup Google OAuth Consent
Google also requires developers to fill out an OAuth consent form to create OAuth credentials. Google uses this consent form to make sure that an application does not abuse its data. If you have not filled out the OAuth Consent yet, please visit here to start the process. You should see an image like the following:
The Google consent page requires you to select whether your application is an external or internal one. Internal applications limit access to accounts within a Google workspace, and you cannot select internal if your Google Cloud project is not a part of a Google Workspace. External applications allow users outside your Google workplace domain to sign up and possibly require you to verify your application with Google. Most use cases pick external over internal. Once you select internal or external, you need to fill out some information on your company. Under the Authorized domains section, you need to add stytch.com.
After filling out your company's information, you can click save and continue for the scopes and test users pages without any changes. Once you are on the summary page, go back to Google OAuth Consent Dashboard. You need to publish your application for prod to avoid the rate limit of 100 users. If you added any restrictive scopes or added a logo, your application needs to be manually verified. This verification can take a couple of days to be reviewed. You can read more about Googles OAuth verification here.
Step 3: Setup Google OAuth Credentials
After setting up the Google project and OAuth consent, go to this page to create the OAuth credentials. There is a create credentials button at the top of the page with an option to create an OAuth client id when selected. When the create OAuth credentials page loads, select Web application (regardless if it is a mobile or non-web application) for the application type and enter a name for your credentials. Under the Authorized redirect URIs section, add the following URL. After you finish creating the OAuth client, Google displays Client ID and client secret in a popup. You will need to enter them into the Stytch Dashboard here.
https://test.stytch.com/v1/oauth/callback/REPLACE_WITH_OAUTH_CALLBACK_IDStep 4: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 5: Add the Google OAuth start URL
Now that Stytch and Google are configured, you need to add Stytch Google OAuth to your application. The Stytch OAuth flow is started by having a user click the Google OAuth Start URL. This URL redirects the user to the Google OAuth sign-in page with all the required OAuth fields prefilled. Your frontend needs to display Stytch Google OAuth Start URL as a button and send the user to that URL when clicked.
https://test.stytch.com/v1/public/oauth/google/start?public_token=PUBLIC TOKENStep 6: Authenticate OAuth request
After Google redirects the user back to Stytch's API, the Stytch API redirects the user to your backend server with a token to either the login redirect URL or the signup redirect URL to verify Stytch redirected the user. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/oauth/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Integrate Google One Tap via the SDK
Implement Google One Tap via the Javascript SDK.
Step 1: Setup Google Project
Before you can use the Stytch Google OAuth flow, you need to enter a Google OAuth client ID and client secret into the Stytch dashboard. Google requires you to create a Google Cloud project to get a client ID and client secret. Please follow the steps here to create one.
Step 2: Setup Google OAuth Consent
Google also requires developers to fill out an OAuth consent form to create OAuth credentials. Google uses this consent form to make sure that an application does not abuse its data. If you have not filled out the OAuth Consent yet, please visit here to start the process. You should see an image like the following:
The Google consent page requires you to select whether your application is an external or internal one. Internal applications limit access to accounts within a Google workspace, and you cannot select internal if your Google Cloud project is not a part of a Google Workspace. External applications allow users outside your Google workplace domain to sign up and possibly require you to verify your application with Google. Most use cases pick external over internal. Once you select internal or external, you need to fill out some information on your company. Under the Authorized domains section, you need to add stytch.com.
After filling out your company's information, you can click save and continue for the scopes and test users pages without any changes. Once you are on the summary page, go back to Google OAuth Consent Dashboard. You need to publish your application for prod to avoid the rate limit of 100 users. If you added any restrictive scopes or added a logo, your application needs to be manually verified. This verification can take a couple of days to be reviewed. You can read more about Googles OAuth verification here.
Step 3: Setup Google OAuth Credentials
After setting up the Google project and OAuth consent, go to this page to create the OAuth credentials. There is a create credentials button at the top of the page with an option to create an OAuth client id when selected. When the create OAuth credentials page loads, select Web application (regardless if it is a mobile or non-web application) for the application type and enter a name for your credentials. Under the Authorized JavaScript origins section, add the origin where One Tap will appear. For example, if you plan on showing One Tap at https://example.com/login, enter https://example.com. If you're using localhost for testing, we recommend adding both http://localhost and http://locahost:[port]. Under the Authorized redirect URIs section, add the URL below. After you finish creating the OAuth client, Google displays Client ID and client secret in a popup. You will need to enter them into the Stytch Dashboard here.
https://test.stytch.com/v1/oauth/callback/REPLACE_WITH_OAUTH_CALLBACK_IDStep 4: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 5: Add the SDK to your app
Now that Stytch and Google are configured, you need to add the Stytch SDK to your application.
import React from "react";
import { Stytch } from "@stytch/stytch-react";
const Login = () => {
const STYTCH_PUBLIC_TOKEN = "PUBLIC TOKEN";
const stytchProps = {
loginOrSignupView: {
products: ['oauth'],
oauthOptions: {
providers: [{
type: 'google',
one_tap: true,
position: 'embedded'
}]
},
},
publicToken: STYTCH_PUBLIC_TOKEN,
};
return (
<div className="sign-in-container">
<Stytch
publicToken={stytchProps.publicToken}
loginOrSignupView={stytchProps.loginOrSignupView}
/>
</div>
);
};
export default Login;Step 6: Authenticate OAuth request
After Google redirects the user back to Stytch's API, the Stytch API redirects the user to your backend server with a token to either the login redirect URL or the signup redirect URL to verify Stytch redirected the user. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/oauth/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Embeddable Magic Links
With our out-of-the-box email magic links product, Stytch is able to fully handle the frustrating and complex pieces of email deliverability, latency, and inbox placement. However, we also offer a flexible way for you to embed magic links into any use case you can imagine. For example, you could send magic links from your own domain, embed them into customized templates, or leverage different communication channels, like sms, to send them. By using our magic link create endpoint, you can embed magic links into all of your end-user communications to reduce friction and improve conversion. If needed, you can always add more authentication requirements to a user’s session to improve security by using the rest of Stytch’s product suite.
Step 1: Create magic link token
Use the magicLinkCreate endpoint to generate a token for a user to embed in your chosen communication (e.g. a promotional email).
curl --request POST \
--url https://test.stytch.com/v1/magic_links \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}'Step 2: Send token
Send your customer communication with the magic link embedded in your main call-to-action button (you'll append the magic link token to the destination URL you're sending the user to).
Step 3: Authenticate token
When the user clicks the link, redirect the user and send a request to Stytch's authenticate endpoint in order to verify the user. You can optionally set a session for the user by using the session_duration_minutes in the authenticate call.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Step 4: Multi-factor authentication
After this step, it's up to you on how you want to handle the user interaction. Depending on the use case, you may not need additional authentication. However, if you want to layer on step-up authentication at any point throughout the user’s session for additional assurance, you can always layer on more verification methods (e.g. SMS, etc.).
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/send \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'Session management
Stytch user sessions are identified by a session token that should be stored client-side (usually a browser cookie) and authenticated on each request. To start a session, use the authenticate magic link or authenticate OTP endpoint as usual and add the session_duration_minutes parameter to set the lifetime of the session. The responses of these endpoints will include a session_token that you can forward to the client and store. Before performing any action that requires authorization, call authenticate session to ensure that the session is still valid.
How to use sessions
Beginning a session
When handling the token for a new authentication factor (authenticate magic link and authenticate OTP), include a session_duration_minutes field to begin a new session. Sessions can be between 5 minutes and one year long. If you provide this field, the authenticate method’s response field will include values for session or session_token.
Authenticating a session
On each request, before doing anything that requires authorization, call authenticate session to ensure that the session is valid. If it is, use the user_id value to identify the user and send the session_token value to the user in a session cookie. If it isn’t valid, clear the session cookie to log the user out and do not process the request. sessions.authenticate always returns the session token for convenience. We recommend following OWASP's guide on cookie storage.
Extending or revoking a session
To extend a session’s lifetime, call authenticate session with the session_duration_minutes parameter. The session will be set to expire that many minutes from now. This will still return the original session token even though its lifetime was extended. To revoke a session, call revoke session with the session ID or session token (whichever is more convenient). We recommend showing the user a list of all their active sessions so they can revoke any they don’t recognize by IP address and/or User-Agent. To attach those values to sessions, add them to the attributes parameter in calls to authenticate magic link or authenticate OTP.
Session management examples
Below are examples of ways to use session management
Remember me for 30 days after login
Create a session that expires 30 days (43200 minutes) after initial login
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"session_duration_minutes": 43200
}'
curl --request POST \
--url https://test.stytch.com/sessions/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'Remember me for 30 days since you last saw me
Everytime a magic link is authenticated, extend the session for another 30 days (43200 minutes)
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"session_duration_minutes": 43200
}'
curl --request POST \
--url https://test.stytch.com/sessions/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_duration_minutes": 43200
}'Log out a user
Log the user out of a given session
curl --request POST \
--url https://test.stytch.com/v1/sessions/revoke \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
}'Log a user out of all sessions
Get all sessions for a given user's ID and individually revoke each of them.
curl --request GET \
--url https://test.stytch.com/v1/sessions?user_id=user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
-u 'PROJECT ID:SECRET'
curl --request POST \
--url https://test.stytch.com/v1/sessions/revoke \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
}'Multiple Authentication Factors
Create a single session from multiple authentication factors.
# Create a new session using the first factor
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"session_duration_minutes": 43200
}'
# Use the session token to attach the second factor
curl --request POST \
--url https://test.stytch.com/v1/otps/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"code": "123456",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'WebAuthn
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.
There are two steps during a WebAuthn authentication flow, registration and authentication. The first step handles registering a WebAuthn device to a user. The second step handles the authentication attempt.
For both the registration and authentication steps, you’ll make two Stytch requests. The first request returns the necessary components to communicate with the WebAuthn device. The second request is used to pass the response from the WebAuthn call back to Stytch for verification.
We’ll be using the webauthn-json library to assist this integration. This library converts the JSON request into the correct data types by unmarshalling and decoding the body and then outputs marshalled JSON that you can pass back to Stytch.
As you’re working through this guide, feel free to ask any questions if you get stuck in our Slack community or reach out to us at support@stytch.com
Step 1: Create Stytch User
If the user attempting to register isn’t associated with a Stytch user ID, you’ll have to add them with Stytch’s /v1/users/create endpoint if you haven’t already. Pass the user’s email address or phone number and store the returned user_id. The user_id will be used to register and authenticate with WebAuthn.
curl --request POST \
--url https://test.stytch.com/v1/users \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com"
}'Step 2: Start Registration Process
To authenticate with WebAuthn, you first need to register an authenticator. This will have to happen once per registration. Start by generating the request needed for webauthn-json’s create call. To do this you’ll make a request to /v1/webauthn/register/start. You need two fields for the request, a Stytch user_id and the domain where the webauthn-json’s create call will be invoked, i.e. your login page’s domain. There are two optional fields, user_agent and authenticator_type. You can pass a user_agent to help identify the WebAuthn registration. This could be helpful for telling registrations apart. You can use authenticator_type to require a certain type of WebAuthn device, either platform (like a fingerprint reader) or cross-platform (like a YubiKey). If you omit the field, we’ll assume either type is acceptable.
curl --request POST \
--url https://test.stytch.com/v1/webauthn/register/start \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"domain": "example.com"
}'Step 3: Calling webauthn-json’s Create Method
Using the public_key_credential_creation_options field from the /v1/webauthn/register/start response, call webauthn-json’s create method. You’ll want to handle any errors that crop up in this step, like if there are no WebAuthn devices available to register. If the WebAuthn call is successful, JSON.stringify the response and get ready for another Stytch call.
import * as webauthnJson from '@github/webauthn-json'
// You implemented this in Step 2
const registerStartData = await callWebauthnRegisterStart()
const credential = await webauthnJson.create({
publicKey: registerStartData.public_key_credential_creation_options
});
// And you'll implement this in Step 4
await callWebauthnRegister({
public_key_credential: JSON.stringify(credential)
})Step 4: Register the WebAuthn Registration with Stytch
Next we’ll use the JSON string you created in Step 3 as the public_key_credential in our request to /v1/webauthn/register. Stytch will validate the credential and return the webauthn_registration_id if the registration is successful. The user now has a registered WebAuthn registration that can be used for authentication. We recommend saving the webauthn_registration_id and domain. This allows you to check that the user in question has a valid WebAuthn registration on file with Stytch before you call /v1/webauthn/authenticate/start for subsequent logins.
curl --request POST \
--url https://test.stytch.com/v1/webauthn/register \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiaFladExOVDlTSWdacVBuS2ZiblFYM25DSjdOYXZUVF9TNm9DOVhSRVl2MEYiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEYwRAIgLEvyXrb_aMCVOjpYBLpm3cPaaquDN0ouXaL27SF9Lp0CIB2f56tWUDvs6oBl3pMxIIrJqJhZKkK7btJtWVDLsFFbaGF1dGhEYXRhWP5Jlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY0VheZqwrc4AAjW8xgpkiwsl8fBVAwB6Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlalAQIDJiABIVggFCI-4HODPxlfeBwfFyzQG_btRm_pB6mb9E1E-rANMwoiWCBCr6C2SQOGElh9N9OMzVBcMnOolAcvz3S0STbnNTHOmg\"},\"clientExtensionResults\":{}}"
}'Step 5: Start Authentication Process
Similar to registering, authentication starts by generating the request for the webauthn-json’s get method. To do this you’ll make a request to /v1/webauthn/authenticate/start. You need two fields for the request, the user_id of the user and the domain the WebAuthn call will be invoked on.
curl --request POST \
--url https://test.stytch.com/v1/webauthn/authenticate/start \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
"domain": "example.com"
}'Step 6: Calling webauthn-json’s Get Method
Using the public_key_credential_request_options field from the /v1/webauthn/authenticate/start response, call webauthn-json’s get method. Again, you’ll want to handle any errors that might arise here. If webauthn-json’s get call is successful, JSON.stringify the response and get ready for another Stytch call.
import * as webauthnJson from '@github/webauthn-json'
// You implemented this in Step 5
const authenticationStartData = await callWebauthnAuthenticateStart()
const credential = await webauthnJson.get({
publicKey: authenticationStartData.public_key_credential_request_options
});
// And you'll implement this in Step 7
await callWebauthnAuthenticate({
public_key_credential: JSON.stringify(credential)
})Step 7: Authenticate the WebAuthn Registration with Stytch
Using the JSON string you created from webauthn-json’s get method as the public_key_credential, make a request to /v1/webauthn/authenticate. Stytch will perform validation on the passed credential and return a 400 if there are any issues. If the authentication is successful, we’ll return a 200.
curl --request POST \
--url https://test.stytch.com/v1/webauthn/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"authenticatorData\":\"SZYN5YgOjGh7NBcPZHZgW1_krrmihjLHmVzzuoNcl2MFYZKokg\",\"clientDataJSON\":\"eyJ2eXBlOjopo2ViYBx0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWEtEWDVJa25EWEU3by1KQlRkYTNfS1NiTXdmb3dMWDQxMldlNEFDY04tYWgiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"signature\":\"MEYCIQDU1FGXEBrq3hsQ2ye1pBcYLMu7zmzLVVdcbs6R21hGyAIhAJmpdBo2Hd7P4Ks9VFKBUYbKSIioMdhl2XIIjWHNKD77\",\"userHandle\":\"dXNlus1kZXZlbG9wLBC2M2E1MGI0LWEwMGEtNGU3NC89NTJmLTFlOGRhODE2nDBnMw\"},\"clientExtensionResults\":{}}"
}'Step 8: You're Done!
You just finished all the critical components to authenticate your users via WebAuthn! Have any feedback after having integrated WebAuthn? Get in touch with us and tell us what you think in our Slack community or via support@stytch.com.
Client libraries
Stytch has official libraries for different programming languages to easily integrate the Stytch API on the back end.
SDKs
Use a client-side SDK to quickly build your user authentication on web and mobile.
Javascript SDK
The Stytch Javascript SDK provides a prebuilt, customizable login UI that you can use to get up and running with Stytch even faster. We offer a plain Javascript version and a React component.
Interested in using the Javascript SDK with a different product? Contact us.
SDK demo
Check out the UI customization options in the SDK here.
CAPTCHA
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!
Email magic links
The Javascript SDK supports our Email Magic Links product. It wraps our login or create user by email endpoint, which finds an existing user or creates a new user and sends them an email magic link.
OAuth
Our Javascript SDK wraps our OAuth start 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, Microsoft, and Apple OAuth.
Parameters
The public token for your project. You can find your public token under the API keys tab in your developer dashboard.
The config object for login or signup functionality.
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 emailMagicLinks and oauth products.
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.
Number of minutes the magic link is valid for.
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.
Number of minutes the magic link is valid for.
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.
An array of OAuth providers you wish to use. Each Provider is an object with a single key. The order of the providers in the array determines the order of the rendered buttons.
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.
See Stytch's storybook for examples.
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.
{ type: 'google', one_tap: boolean, position: 'embedded' | 'floating' }Adds the Microsoft OAuth start button.
{ type: 'microsoft' }Adds the Apple OAuth start button.
{ type: 'apple' }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.
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.
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.
The font family that will apply to all text in the SDK.
Your primary brand color. This color will be applied to primary actions, like buttons.
The color for most of the text in the SDK.
The color for secondary text in the SDK, such as disclaimers.
A light grey color that will be applied to visual elements in the SDK.
A dark grey color that will be applied to visual elements in the SDK.
The width of the SDK.
When this value is false, the title and description text will not show in the SDK.
Optional callbacks that are triggered by various events in the SDK. See more details about the callbacks here.
A callback function that responds to events sent from the SDK. For now, this includes a USER_EVENT_TYPE.
A callback function that responds to successfully sending a magic link.
A callback function that responds to errors in the SDK. It is useful for debugging during development and error handling in production.
EXAMPLE
import React from "react";
import { Stytch } from "@stytch/stytch-react";
const Login = () => {
const STYTCH_PUBLIC_TOKEN = "PUBLIC TOKEN";
const stytchProps = {
loginOrSignupView: {
products: ['emailMagicLinks', 'oauth'],
emailMagicLinksOptions: {
loginRedirectURL: "https://example.com/authenticate",
loginExpirationMinutes: 30,
signupRedirectURL: "https://example.com/authenticate",
signupExpirationMinutes: 30,
createUserAsPending: true,
},
oauthOptions: {
providers: [{type: 'google', 'one_tap': true, position: 'floating'}, {type: 'microsoft'}]
},
},
style: {
fontFamily: 'Arial',
width: '321px',
primaryColor: '#106ee9',
},
publicToken: STYTCH_PUBLIC_TOKEN,
callbacks: {
onEvent: (data) => {
// TODO: check whether the user exists in your DB
const userExists = false;
if (data.eventData.type === 'USER_EVENT_TYPE' && !userExists) {
fetch("/users", {
method: "POST",
body: JSON.stringify({
userId: data.eventData.userId,
email: data.eventData.email,
}),
});
}
},
onSuccess: (data) => console.log(data),
onError: (data) => console.log(data),
},
};
return (
<div className="sign-in-container">
<Stytch
publicToken={stytchProps.publicToken}
loginOrSignupView={stytchProps.loginOrSignupView}
style={stytchProps.style}
callbacks={stytchProps.callbacks}
/>
</div>
);
};
export default Login;Callbacks
Callbacks are optional functions for the Javascript SDK.
onEvent
A function that is called when a Stytch user is retrieved or created. The function expects an argument of an event object. The object has eventType and eventData objects.
{
"eventType": "CALLBACK_EVENT",
"eventData": {
"type": "USER_EVENT_TYPE",
"userId": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"emailId": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"email": "example@stytch.com"
}
},onSuccess
{
"eventType": "SUCCESS_EVENT",
"eventData": {
"message": "Successfully sent magic link to example@stytch.com",
}
},onError
A function that is called when a error occurs. The function expects an argument of an event object. The object has eventType and eventData objects.
{
"eventType": "ERROR_EVENT",
"eventData": {
"message": "Error sending magic link",
}
},Asynchronous and deferred loading
Asynchronous loading of JavaScript can help improve the user experience of your site by not blocking DOM rendering during script loading. If you don't initially show the Login SDK to users — for example, if it is hidden in a modal — you can avoid blocking DOM rendering by adding an async or defer attribute to the script. Note that the global Stytch function will not be available until after the script has loaded. If you plan on showing the Login SDK to users immediately, we do not recommend using these attributes.
<script id="js-stytch" defer src="https://js.stytch.com/stytch.js"></script>
<script>
var script = document.querySelector("#js-stytch");
script.addEventListener("load", function () {
var STYTCH_PUBLIC_TOKEN = "PUBLIC TOKEN";
var stytch = Stytch(STYTCH_PUBLIC_TOKEN);
stytch.mount(...)
});
</script>iOS SDK
The Stytch iOS SDK provides a prebuilt, customizable login UI that you can use to get up and running with Stytch even faster. Explore the iOS SDK here on GitHub.
Customization
You can customize prebuilt UI by setting StytchUI customization's values
Style object for text UI
Text font
Text size
Text color
Title text style
Show/hide title
Subtitle text style
Show/hide subtitle
Input text style
Input placeholder text style
Input field background color
Input field border color
Input field corner radius
Action button text style
Action button background color
Action button corner radius
Show/hide brand logo
backgroundColor
Android SDK
The Stytch Android SDK provides a prebuilt, customizable login UI that you can use to get up and running with Stytch even faster. Explore the Android SDK here on GitHub.
Also, take a look at this example app that demonstrates how to integrate with the Stytch SDK.
Requirements
The SDK supports API level 21 and above (distribution stats).
- - minSdkVersion = 21
- - Android Gradle Plugin 4.1.1
- - AndroidX
Customization
You can customize prebuilt UI by setting StytchUI customization's values
Style object for text UI
Text size in sp
Text color
Text font
Window background color
If true, no toolbar/action bar will be shown at top of screen
Toolbar/Action bar color
Title text style
Subtitle text style
(SMS Passcode flow only) SMS consent text style
User input (email/phone number/passcode) text style
Input hint text style
Background color of input boxes
Radius of rounded corners of input boxes, in dp
Button text style
Set a different text color when buttons are in the disabled state
Button background color when in enabled state
Button background color when in disabled state
Radius of rounded corners of buttons, in dp
Error message text style
Security
Stytch services are designed, developed, monitored, and updated to protect you and your users's data and privacy. Stytch is compliant with a range of industry standards and frameworks that assist with your own security and regulatory needs.
- SOC 2 - Stytch maintains a SOC 2 type II report attesting to the company’s compliance with the AICPA’s Trust Service Criteria.
- HIPAA - Stytch is compliant with the Health Insurance Portability and Accountability Act as a business associate.
- GDPR & CCPA - Stytch is committed to complying with and helping its customers comply with the General Data Protection Regulation (GDPR) and California Consumer Privacy Act (CCPA).
Responsible disclosure
If you believe you’ve discovered a potential vulnerability, please let us know by emailing us at security@stytch.com. We will acknowledge your email within 48 hours. Provide us with a reasonable amount of time to resolve the issue before disclosing it to the public or a third party. We aim to resolve critical issues within 30 days of disclosure. Make a good faith effort to avoid violating privacy, destroying data, or interrupting or degrading the Stytch service. Please only interact with accounts you own or for which you have explicit permission from the account holder. While researching, please refrain from:
- Distributed Denial of Service (DDoS)
- Spamming
- Social engineering or phishing of Stytch employees or contractors
- Any attacks against Stytch’s physical property or data centers
Thank you for helping to keep Stytch and our users safe!
Privacy policy
See here for our current privacy policy.
Resources
Learn more about how Stytch works.
API keys
The Stytch API uses basic authentication with your project_id and secret. There are two environments, TEST and LIVE, and the API keys as well as urls, test.stytch.com and api.stytch.com respectively, are unique to each environment.
Supported browsers
Stytch.js strives to support all recent versions of major browsers:
- Chrome and Safari on all platforms
- Firefox on desktop platforms
- TLS 1.2 must be supported by the browser
If you encounter a bug with other platforms, let us know and we'll prioritize fixing based on popularity of the given browser and severity of the bug.
Testing
In some scenarios, it may be helpful to test sending a magic link without actually sending an email. You can use the email sandbox@stytch.com to test sending a magic link. If your API credentials and the request format are correct you will receive a 200 status response, but no email will actually be sent.
You can use the following test tokens to test the authenticate magic endpoint and receive the corresponding responses.
200 Success: DOYoip3rvIMMW5lgItikFK-Ak1CfMsgjuiCyI7uuU94=
401 Unauthorized: 3pzjQpgksDlGKWEwUq2Up--hCHC_0oamfLHyfspKDFU=
404 Magic link not found: CprTtwhnRNiMBiUS2jSLcWYrfuO2POeBNdo5HhW6qTM=
You can use the following session tokens to test the authenticate session endpoint.
200 Success: WJtR5BCy38Szd5AfoDpf0iqFKEt4EE5JhjlWUY7l3FtY
404 Session not found: 59cnLELtq5cFVS6uYK9f-pAWzBkhqZl8AvLhbhOvKNWw
IP validation
You can specify up to 10 IPs that your requests must come from to ensure that only your servers are able to access the Stytch API. By default we allow all IPs. If you'd like to add IP validation, send an email to support@stytch.com with the subject "IP Validation" with your live project ID and the IPs you'd like to allow (max 10 IPs).
Integrations
Learn how to integrate Stytch with common technologies and frameworks.
Replacing Firebase with email magic links
Integrate Stytch email magic links as a replacement for your Firebase integration. Both sign-up and login flows will be merged into a single, passwordless flow.
Step 1: Update your login UI
Here’s an example of a login component when Stytch is the only login method.
Step 2: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 3: Log in or create user
The LoginOrCreateUser endpoint will be used to replace any methods used to log in or sign up a user, like Firebase’s SignupNewUser and VerifyPassword endpoints. This request will either send a login or create magic link to the user based on if the email is associated with a user already. If the user is created, shown by the user_created attribute in the response, save the user ID from the response to use with other Stytch endpoints. This needs to happen once per user. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID. The login_magic_link_url and signup_magic_link_url request parameters are the URLs the user will be redirected to from the email depending on if the user was existing or created respectively.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/login_or_create \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"login_magic_link_url": "https://example.com/login",
"signup_magic_link_url": "https://example.com/signup"
}'Step 4: Authenticate magic link
The AuthenticateMagicLink endpoint will be used in conjunction with all LoginOrCreateUser requests. When the user opens the email, they are prompted to sign in or log in by clicking the provided login_magic_link_url or signup_magic_link_url from the LoginOrCreateUser request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Step 5: How to replace Firebase endpoints
Both the sign up and log in flows that are separate with Firebase will merge into a single flow with Stytch. Rather than calling Firebase’s SignUp or SignInWithPassword endpoints based on if the user exists or not, you can just call our LoginOrCreateUser endpoint. After the user clicks on the email magic link, call AuthenticateMagicLink with the token passed in the query params. The response dictates if the user should be logged in or not.
Step 6: Session management
While we work to integrate session management into our feature set, you’re welcome to continue using the same Firebase endpoints to manage your tokens. This can be done in parallel with our Magic Link feature. After a user has been authenticated via the AuthenticateMagicLink endpoint, continue by making a request to Firebase’s CustomToken or similar endpoints to manage tokens.
Replacing AWS Cognito with email magic links
Integrate Stytch email magic links as a replacement for your AWS Cognito integration. Both sign-up and login flows will be merged into a single, passwordless flow.
Step 1: Update your login UI
Here’s an example of a login component when Stytch is the only login method.
Step 2: Add redirect URLs to the Stytch dashboard
Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.
Step 3: Log in or create user
The LoginOrCreateUser endpoint will be used to replace any methods used to log in or sign up a user, like Cognito’s InitiateAuth and SignUp endpoints. This request will either send a login or create magic link to the user based on if the email is associated with a user already. If the user is created, shown by the user_created attribute in the response, save the user ID from the response to use with other Stytch endpoints. This needs to happen once per user. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID. The login_magic_link_url and signup_magic_link_url request parameters are the URLs the user will be redirected to from the email depending on if the user was existing or created respectively.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/login_or_create \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "test@stytch.com",
"login_magic_link_url": "https://example.comlogin",
"signup_magic_link_url": "https://example.comsignup"
}'Step 4: Authenticate magic link
The AuthenticateMagicLink endpoint will be used in conjunction with all LoginOrCreateUser requests. More specifically, it will replace methods that authenticate a user’s email or password, like ConfirmSignUp and InitiateAuth. When the user opens the email, they are prompted to sign in or log in by clicking the provided login_magic_link_url or signup_magic_link_url from the LoginOrCreateUser request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, the user is verified and can be logged in.
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'Step 5: How to replace AWS Cognito endpoints
Both the sign up and log in flows that are separate with AWS Cognito will merge into a single flow with Stytch. Rather than calling AWS Cognito’s SignUp or InitiateAuth endpoints based on if the user exists or not, you can just call our LoginOrCreateUser endpoint. After the user clicks on the email magic link, call AuthenticateMagicLink with the token passed in the query params. The response dictates if the user should be logged in or not. This request replaces AWS Cognito’s endpoints like ConfirmSignUp.
Step 6: Session management
While we work to integrate session management into our feature set, you’re welcome to continue using the same AWS Cognito endpoints to manage your tokens. This can be done in parallel with our Magic Link feature. After a user has been authenticated via the AuthenticateMagicLink endpoint, continue by making a request to AWS Cognito’s InitiateAuth with the user’s username and password to get the access tokens as you have been. This will require you to store the user’s username & password if you’ve relied on AWS Cognito to store them before. You will have to generate passwords for new users to use their InitiateAuth endpoint.
Stytch and Planetscale for user authentication
Use Stytch and Planetscale to build out your entire user authentication flow and database.
Step 1: Please use Node to continue this integration guide
This guide is only supported for Node. Please select Node in the language selector at the top of this page to view this guide.