Welcome to Docs

Stytch allows you to build frictionless, secure, and engaging authentication flows. Stytch offers a wide variety of authentication methods and two ways of integration to suit the needs of your users and your product.

Backend API

Stytch’s direct API integration considers both developer and user experience to ensure fast, safe, and easy authentication flows. We make integration quick and painless, with official client libraries you can leverage and a clear, comprehensive API reference.

Client libraries

Frontend SDKs

Stytch SDKs allow you to build authentication with minimum backend code. With our SDKs, use your own UI or leverage our highly customizable pre-built UI flows.

JavaScript SDK

Available in vanilla JS and React


React Native SDK

Works with both Expo and bare React Native projects


iOS SDK

Written in Swift and works with iOS, macOS, and tvOS


Coming Soon



Example apps

Learn more about how Stytch works and get up and running quickly using an example app. Want to dive into the products but not the code? Try out our demo 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!

example app

Built by the community

Check out these great example apps and templates built by our community!

Argyle + Unit + Stytch API

Example app that integrates Argyle for payroll data, Unit for account opening, and Stytch for authentication

Feathery + Stytch API

Build a drag-and-drop signup flow with Feathery's Stytch integration and template

n.xyz + Stytch JS SDK

Example app that integrates Stytch for Web3 authentication and n.xyz for pulling Web3 data

example app

Security

Stytch services are designed, developed, monitored, and updated with security at our core to protect you and your customers’ data and privacy.

Overview

To deliver our services while protecting the confidentiality, integrity, and availability for all our customers, we operate under a shared security responsibility model. This model is adopted by many organizations to identify the respective responsibilities of Stytch and our customers. In this model, Stytch is responsible for the security of the Stytch services and Stytch customers are responsible for the security of their specific configurations within the respective implementations of Stytch services.

Stytch’s responsibility: Stytch is responsible for the security of the services and underlying infrastructure.

Customer responsibility: Stytch customers are responsible for securing their respective configurations and permissions that they enable within Stytch services for their projects. This includes ensuring that customer projects have the correct user permissions set, keys and tokens are appropriately secured within your internal systems, IPs are validated, etc.

Infrastructure & physical security

Stytch leverages highly available and secure cloud infrastructure across multiple platforms to ensure that our services are always available and securely delivered.

All Stytch hardware and networking is routinely updated and audited to ensure systems are secure and that least privileged access is followed. Additionally we implement robust logging and audit protocols that allow us high visibility into system use.

Personnel security

Security of Stytch services starts with our employees, which is why we foster a culture of security and approach every question with an eye towards safety. Upon hire and annually thereafter, all employees complete training courses designed to cover Stytch information security practices, privacy practices and requirements, as well as responding to social engineering attacks. Software developers are also required to complete additional courses related to secure software development.

Stytch follows the principles of least privilege and segregation of duties wherever possible. Stytch requires that all access to its infrastructure, applications, and data be controlled based on business and operational requirements with users only being provisioned the minimum set of privileges required to perform their required job responsibilities.

When personnel leave Stytch, all of their respective user accounts, passwords, hardware, and badges are revoked.

Service level security

Policies and procedures are in place for handling data processed, stored, and transmitted by Stytch. Data elements are inventoried and classified according to their sensitivity and applicable audience in accordance with Stytch’s Data Classification Policy. Customer confidential data is retained in accordance with contractual terms and regulatory requirements.

Stytch requires requests to Stytch services to be encrypted using Transport Layer Security (TLS) using certificates from an established third party certificate authority. Sensitive data is encrypted at rest using Advanced Encryption Standard (AES) 256-bit encryption algorithm or better.

Penetration tests

As part of our security program, we conduct internal security tests, third party penetration tests, and respond to reported vulnerabilities from the public. Identified vulnerabilities are triaged and mitigated in accordance with contractual requirements and internal service level agreements.

Responsible disclosure program

Here at Stytch, we take the security of our user’s data and of our services seriously. As such, we encourage responsible security research on Stytch services and products. 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 2 business days. As public disclosures of a security vulnerability could put the entire Stytch community at risk, we ask that you keep such potential vulnerabilities confidential until we are able to address them. We aim to resolve critical issues within 30 days of disclosure. Please 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

Stytch is committed to protecting the personal data of our customers and their customers. Stytch has in place appropriate data security measures that meet industry standards. We regularly review and make enhancements to our processes, products, documentation, and contracts to help support ours and our customers’ compliance for the processing of personal data.

See our current privacy policy here.

Compliance

Stytch is committed to trust and transparency. As such, we have a publicly available status site at which you can see the current status of our services, past incidents, as well as subscribe to updates.

Stytch is compliant with a range of industry standards and frameworks that assist with your own security and regulatory needs:

  • SOC 2 Trust Service Criteria - Stytch maintains a SOC 2 type II report attesting to the company’s compliance with the AICPA’s Trust Service Criteria for Security, Availability, and Confidentiality. For a copy of our report, please reach out to our support team.
  • 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 (EU 2016/679 GDPR) and California Consumer Privacy Act (2018 CCPA). We’ve made enhancements to our services, processes, and contract documents in order to help our customers meet their GDPR and CCPA compliance requirements.


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

Stytch provides sandbox values which can be used to receive sample responses in the Test environment.


Magic Links

In some scenarios, it may be helpful to test sending a magic link without actually sending an email. You can use the email address 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 tokens in the /magic_links/authenticate endpoint and receive the corresponding responses.

  • 200 Success: DOYoip3rvIMMW5lgItikFK-Ak1CfMsgjuiCyI7uuU94=

  • 401 unable_to_auth_magic_link: 3pzjQpgksDlGKWEwUq2Up--hCHC_0oamfLHyfspKDFU=

  • 404 magic_link_not_found: CprTtwhnRNiMBiUS2jSLcWYrfuO2POeBNdo5HhW6qTM=


One-time Passcodes (OTP)

In some scenarios, it may be helpful to test sending a One-time Passcode (OTP) without actually sending a message. You can use the phone number +10000000000, for our /otps/sms/send and /otps/whatsapp/send endpoints, and sandbox@stytch.com for our /otps/email/send endpoint, to test sending an OTP in our Test environment. If your API credentials and the request format are correct, you will receive a 200 status response but no message will actually be sent.

You can use the following code, and the method_id you received in the 200 response from /otps/xxx/send, in the /otps/authenticate endpoint and receive the corresponding response.

  • 200 Success: 000000


OAuth Logins

The following tokens can be used in order to test the /v1/oauth/authenticate endpoint.

  • 200 Success: hdPVZHHX0UoRa7hJTuuPHi1vlddffSnoweRbVFf5-H8g

  • 400 oauth_token_not_found: 59cnLELtq5cFVS6uYK9f-pAWzBkhqZl8AvLhbhOvKNWw


Session Management

You can use the following session_tokens to test the /sessions/authenticate endpoint.

  • 200 Success: WJtR5BCy38Szd5AfoDpf0iqFKEt4EE5JhjlWUY7l3FtY

  • 404 session_not_found: 59cnLELtq5cFVS6uYK9f-pAWzBkhqZl8AvLhbhOvKNWw


Crypto Wallets

The following crypto wallet address can be used in order to test the /v1/crypto_wallets/authenticate/start and /v1/crypto_wallets/authenticate endpoints along with the ethereum wallet type.

  • 200 Success: 0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1-H8g


Time-based One-time Passcodes (TOTP)

To test the creation of TOTPs you can use the following user_idin the Test environment with the /v1/totps endpoint. You can use the same user_id to test /v1/totps/recovery_codes as well.

  • user_id: user-test-e3795c81-f849-4167-bfda-e4a6e9c280fd

You can use the following totp_codes along with the above user_id to test the /v1/totps/authenticate endpoint.
  • 200 Success: 000000

  • 401 unable_to_authenticate_totp: 401401

You can use the following recovery_codes along with the above user_id to test the /v1/totps/recover endpoint.
  • 200 Success: a1b2-c3d4-e5f6

  • 401 unable_to_authenticate_recovery_code: 0u1v-2w3x-4y5z

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

Account enumeration

An account enumeration attack occurs when a bad actor tries to identify valid users, emails, etc within an app's authentication flow. Account enumeration is primarily used to gain information about a system that can be used in further attacks, and does not directly result in compromised accounts.

Example

In order for account enumeration to occur, your app must expose some information about a user's state. For example, if you leverage our Email Magic Links Send endpoint, this endpoint requires that a user already exist before a magic link may be sent. That means if a bad actor enters an arbitrary email address, the Send endpoint will return a 200 success response if that email address exists as a user in your app and a 404 error response if that email address does not exist in your app. Using the Email Magic Links Login or Create endpoint will always send an email, and will always return a consistent response and will not reveal whether the email address already existed in the application or not.

This exposes to the bad actor that an email address belongs to a user of your app and the bad actor may leverage this information in a subsequent attack to phish, or compromise this user.

Recommendations

Generally account enumeration does not represent a major risk to your application, non-sensitive consumer applications carry very little risk from account enumeration. In fact, account enumeration via useful and actionable error messages is often helpful for consumer login flows. For example, telling a user that their login failed because they do not have an account is a better user experience than presenting a generic failure message.

However if your domain is particularly sensitive to security, e.g. government, fintech, healthcare etc, or your application is at a large enough scale, we do recommend you take a few steps to protect your against account enumeration.
  • Don't use error messages that give away key information about why a particular action failed. For example, if an actor initiates a password reset for an account that does not exist, don't show an error message. Instead, show a message to the effect of "If an account is associated with that email, a reset link has been sent."
  • Don't expose unmasked Personally Identifiable Information (PII), e.g. only display the last four digits of a phone number in your UI as opposed to the full value.
  • Limit how much user state you share with your frontend (user-facing client).
  • If you're using our frontend SDKs, the Send methods will error if the user hasn't been pre-created. If this is critical, we recommend disabling the Send methods and exclusively using the LoginOrCreate methods, or using our API directly from your backend.


Migrations

Guides for migrating to Stytch from common solutions


Auth0 to Stytch migration guide

This guide covers the process of migrating an existing user base from Auth0 to Stytch. This document assumes you are using Auth0’s Universal Login product.


You will also need to create a Stytch account if you have not already.

Docs Guide Image
  1. Overview

    A Stytch migration has three core steps:

    • 1. Export users from Auth0
    • 2. Import users to Stytch
    • 3. Transition authentication application logic from Auth0 to Stytch

    Consider first running this migration in a Stytch test environment to validate success before moving to your live environment.

  2. Export users

    In order to create a user in the Stytch API you will need the user’s email address as it will act as the primary identifier. Stytch and Auth0 share two additional common fields on the User object: name and phone number; you can choose to migrate this data as well. If there is other data stored on your Auth0 user model you may consider exporting that data to an external database depending on your circumstances.

    There are several ways to export user data from Auth0, the management API and the dashboard UI. The two recommended routes are either using the User Import / Export Extension or the Bulk User Exports API endpoint. Be sure that the email field is included in this export.

    Configure either approach to produce a JSON or CSV file and save this file on your local machine.

  3. Import users

    In order to import your users into Stytch you will use our Create user endpoint. This endpoint creates one user at a time, so you will need to leverage a script to parse your exported user data, and run a loop to create each user.

    Below is a sample script you can use as a template for importing your users.

    # Loop over this command for each user
    curl --request POST \
    	--url https://test.stytch.com/v1/users \
    	-u 'PROJECT_ID:SECRET' \
    	-H 'Content-Type: application/json' \
    	-d '{
    		"email": "sandbox@stytch.com"
    	}'
  4. Transition authentication logic

    Before making the switch you will need to build a passwordless authentication flow powered by Stytch. You can use one of our SDKs which comes with pre-built login UI components or you can build your own UI and connect with Stytch using a headless SDK or direct API integration. There are many guides for getting started with Stytch for all of our products.

    Once your authentication flow is built, and your users have been created within Stytch, you can remove Auth0, and begin directing your users to your Stytch powered authentication flow. There are two options to consider here, a hard cutover or a rolling migration, to complete this transition.

    Hard cutover

    A hard cutover means migrating your entire user base and at a set time by transitioning all your users to the new, Stytch powered authentication UI.

    This option is the most straightforward and is best to use when you’re ready to move quickly as it removes any need to build secondary logic to aid in the migration.

    Rolling migration

    A rolling migration involves directing a growing percentage of your traffic to the Stytch powered authentication UI. For example, start by directing 5% of your traffic to the new Stytch powered login flow while the remaining users are on your legacy flow, then increase this percentage over a couple days until 100% of your users are on Stytch. This strategy allows you to quickly and easily adjust your transition if necessary.

    This strategy requires a few bits of additional logic in your app to ensure a smooth transition:

    • - A feature flag within your authentication flow that bifurcates your user base between Stytch and Auth0 at a controllable percentage.
    • - You’ll need to set a cookie (or similar) on each user’s device that tracks which authentication flow to present.
    • - For new users that go through your sign up flow via Stytch, you will need to create a record in Auth0 to handle the edge case where this user returns logged out on a different device and is presented with the Auth0 authentication UI.
  5. You're done!

    After all of your users are migrated to Stytch, you can remove your legacy Auth0 flow and your users can enjoy the smooth, frictionless login experience you just created.

    Share your experience with us and our developer community on Slack, we would love to hear how it went!

  6. User account deduplication

    Stytch uses email as a primary key for identifying users. This means if you are using a combination of the Stytch Email Magic Links product and OAuth Logins then Stytch will automatically deduplicate users with matching email addresses. For example, if you create an account via Email Magic Links using the email address example@stytch.com, and then later login with a Google account which is tied to example@stytch.com Stytch will treat these as the same user. Auth0 treats each social login as a separate IdP and leaves it up to the developer to merge accounts. For this reason, you may need to merge your users accounts before migrating to Stytch, if your script attempts to manually create two users in Stytch via the Create users endpoint with the same email address, you will receive a duplicate_email error.


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.

  1. Step 1: Update your login UI

    Here's an example of a login component when Stytch is the only login method.

    Step description
  2. 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.

  3. 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": "sandbox@stytch.com",
            "login_magic_link_url": "https://example.comlogin",
            "signup_magic_link_url": "https://example.comsignup"
        }'
  4. 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.

  5. Step 6: Session management

    Stytch provides end-to-end session management which integrates seamlessly with the Email Magic Link flow. To start a Stytch session include a session_duration_minutes parameter in your authenticate magic link call. To learn more about sessions review the session management guide .

    You are also welcome to continue using the same AWS Cognito endpoints to manage your tokens. 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.


Firebase to Stytch migration guide

This guide covers the process of migrating an existing user base from Firebase to Stytch.


If you need help at any step along the way, reach out to us at support@stytch.com or reach out to us on Slack!

Docs Guide Image
  1. Overview

    A Stytch migration has three core steps:

    • 1. Export users from Firebase
    • 2. Import users to Stytch
    • 3. Transition authentication application logic from Firebase to Stytch

    Consider first running this migration in a Stytch test environment to validate success before moving to your live environment.

  2. Export users

    You’ll be using the Firebase CLI to export your users from Firebase. When you export your users via the CLI, you’ll need the user’s email address or phone number depending upon which Stytch product you’ll be using.

    If you’re using an email based authentication like Email Magic Links or Google OAuth, be sure to export the email address, if you’re using phone number based authentication like Passcodes via SMS, you’ll want to export the user’s phone number. This guide assumes that you’re using email based authentication, however the steps will be the same for phone numbers.

    To run the export you’ll use a command like the one below. If you prefer to work with JSON, subsistitute --format=json in the command.

    firebase auth:export firebase-users.json --format=csv --project <PROJECT_ID>
  3. Import users

    In order to import your users into Stytch you will use our Create user endpoint. This endpoint creates one user at a time, so you will need to leverage a script to parse your exported user data, and run a loop to create each user.

    Below is a sample script you can use as a template for importing your users.

    # Loop over this command for each user
    curl --request POST \
    	--url https://test.stytch.com/v1/users \
    	-u 'PROJECT_ID:SECRET' \
    	-H 'Content-Type: application/json' \
    	-d '{
    		"email": "sandbox@stytch.com"
    	}'
  4. Transition authentication logic

    Before making the switch you will need to build a passwordless authentication flow powered by Stytch. You can use one of our SDKs which comes with pre-built login UI components or you can build your own UI and connect with Stytch using a headless SDK or direct API integration. There are many guides for getting started with Stytch for all of our products.

    Once your authentication flow is built, and your users have been created within Stytch, you can remove Firebase, and begin directing your users to your Stytch powered authentication flow. There are two options to consider here, a hard cutover or a rolling migration, to complete this transition.

    Hard cutover

    A hard cutover means migrating your entire user base and at a set time by transitioning all your users to the new, Stytch powered authentication UI.

    This option is the most straightforward and is best to use when you’re ready to move quickly as it removes any need to build secondary logic to aid in the migration.

    Rolling migration

    A rolling migration involves directing a growing percentage of your traffic to the Stytch powered authentication UI. For example, start by directing 5% of your traffic to the new Stytch powered login flow while the remaining users are on your legacy flow, then increase this percentage over a couple days until 100% of your users are on Stytch. This strategy allows you to quickly and easily adjust your transition if necessary.

    This strategy requires a few bits of additional logic in your app to ensure a smooth transition:

    • - A feature flag within your authentication flow that bifurcates your user base between Stytch and Firebase at a controllable percentage.
    • - You’ll need to set a cookie (or similar) on each user’s device that tracks which authentication flow to present.
    • - For new users that go through your sign up flow via Stytch, you will need to create a record in Firebase to handle the edge case where this user returns logged out on a different device and is presented with the Firebase authentication UI.
  5. You're done!

    After all of your users are migrated to Stytch, you can remove your legacy Firebase flow and your users can enjoy the smooth, frictionless login experience you just created.

    Share your experience with us and our developer community on Slack, we would love to hear how it went!

  6. User account deduplication

    Stytch uses email or phone number as a primary key for identifying users. This means if you are using a combination of the Stytch Email Magic Links product and OAuth Logins then Stytch will automatically deduplicate users with matching email addresses. For example, if you create a user via Email Magic Links using the email address example@stytch.com, and then later login with a Google account which is tied to example@stytch.com, Stytch will treat these as the same user.

    For this reason, you may need to merge your users accounts before migrating to Stytch, if your script attempts to manually create two users in Stytch via the Create users endpoint with the same email address, you will receive a duplicate_email error.



Integrations

Learn how to integrate Stytch with common technologies and frameworks.


Stytch and Planetscale for user authentication

Use Stytch and Planetscale to build out your entire user authentication flow and database.

Docs Guide Image
  1. 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.


Stytch and Supabase

Check out the Stytch integration guide in the Supabase documentation. In this guide you will build a simple expense tracker application using Stytch for authentication and Supabase as a database.

Docs Guide Image

    Stytch and Feathery

    Use Stytch and Feathery to build powerful forms with a visual editor, custom logic, and extensible code. With Feathery's Stytch integration, you can build forms that handle authenticated login and signup.

    Check out the Stytch and Feathery integration guide to get started.

    Docs Guide Image