The Stytch React Native SDKs provide the easiest way for you to use Stytch in your React Native projects. We provide separate SDKs for Expo managed workflows as well as bare React Native projects to ensure ease of installation and use, as well as compatibility with iOS and Android builds. Using the SDKs allows you to easily authenticate your users without adding extra endpoints to your backend.
Compatibility and requirements
The Expo SDK is compatible with all actively supported Expo versions (currently Expo 41+).
The Expo SDK also supports all versions of iOS and Android supported by Expo (currently Android 5+ and iOS 11+)
The React Native SDK is compatible with React Native 0.60+
Supported authentication products
Email magic links
One-time passcodes
Biometrics
Passwords
Session management
User management
Installation
Install the relevant package(s) as a project dependency via npm or yarn.
If you are using Stytch's biometrics product, you will also need to install @stytch/react-native-modules. If you are using an "ejected" Expo setup (required for installing packages with custom native modules, learn more in the Expo docs), you will also need to install @react-native-async-storage/async-storage.
Initialize the SDK by creating a new StytchClient object provided in the package. We recommend storing the created client instance in a common file to use it in JavaScript methods such as Redux actions.
You do not need to manually link, but will need to run pod install if you are using @stytch/react-native.
StytchClient parameters
public_token*string
Provide the public token from the Stytch dashboard. This value is safe to embed client side.
At the root level of your application, initialize a new StytchProvider object using your public token. to provide all components with access to the StytchClient as well as User and Session data via hooks.
StytchProvider props
stytch*StytchClient | null
Provide the previously created StytchClient object.
To authorize the Stytch SDK to run in your application, you must first add an Authorized Environment Bundle ID to your Stytch SDK Configuration.
Any application published to the Apple App Store or the Google Play Store must have a unique ID. In iOS development, this is referred to as a bundle identifier, and in Android it is referred to as the Application ID or package name.
If the bundle identifier / package name does not match the Authorized Environment Bundle ID in your Stytch SDK Configuration, then you will receive an invalid_mobile_identifier error on any requests made through the SDK. If you are encountering this error, ensure that you've followed the steps in this configuration correctly.
For bare React Native projects, the process takes a few extra steps, and there are separate processes for updating iOS bundle identifier vs. the Android package name.
For iOS, you first open the general settings for the project in Xcode. To get there, open the project workspace, and select the appname project from the project navigator. Once you've opened the general settings for the project, simply update the Bundle Identifier field.
For Android, there a number of steps. Firstly, you'll need to rename the folder structure inside android/app/src/main/java to reflect the package name for your project. If you had initialized your project with the name HelloWorld, you would find two files MainActivity.java and MainApplication.java inside android/app/src/main/java/com/helloworld. If you wanted to change your package name to com.myapp.test you'd have to update the folder structure so that those two files were insideandroid/app/src/main/java/com/myapp/test. After you've updated your folder structure, you need to update:
The package name on line 1 of MainActivity.java
The package name on line 1 of MainApplication.java
Line 2 of /android/app/src/main/AndroidManifest.xml
The package value for android_build_config and android_resource in /android/app/BUCK
The applicationId value in defaultConfig for the /android/app/build.gradle file.
One-time passcodes can be sent via email, phone number, or WhatsApp. One-time passcodes allow for a quick and seamless login experience on their own, or can layer on top of another login product like Email magic links to provide extra security as a multi-factor authentication (MFA) method.
Methods
To call these methods, One-time passcodes must be enabled in the SDK Configuration page of the Stytch dashboard.
Login Or Create via SMS
The Login or create method wraps Stytch's login_or_create via SMS API endpoint. Call this method to send an SMS passcode to new or existing users.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
The Send method wraps Stytch's send via SMS API endpoint. Call this method to send an SMS passcode to existing users. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.
This method is also used when you need to add a phone number to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs a phone number that does not match one on their Stytch User object, upon successful authentication the new phone number will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
The Login or create method wraps Stytch's login_or_create via email API endpoint. Call this method to send an email passcode to new or existing users.
Method parameters
email*string
The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Sign-up.
The Send method wraps Stytch's send via email API endpoint. Call this method to send an email passcode to existing users. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.
This method is also used when you need to add an email address to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs an email address that does not match one on their Stytch User object, upon successful authentication the new email address will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
email*string
The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Sign-up.
The Login or create method wraps Stytch's login_or_create via WhatsApp API endpoint. Call this method to send a WhatsApp passcode to new or existing users.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
The Send method wraps Stytch's send via WhatsApp API endpoint. Call this method to send a WhatsApp passcode to existing users. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.
This method is also used when you need to add a phone number to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs a phone number that does not match one on their Stytch User object, upon successful authentication the new phone number will be added to the existing user. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
phone_number*string
The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.
Configurationobject
Additional configuration.
Collapse
expiration_minutesint
Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
The authenticate method wraps the authenticate one-time passcode API method which validates the code passed in. If this method succeeds, the user will be logged in, granted an active session, and the session data will be persisted on device.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook.
Method parameters
method_id*string
The email_id or phone_id where the OTP was delivered. This value will be returned in the associated /login_or_create or /send response.
code*string
The code to authenticate.
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The React Native SDK provides methods to send and authenticate magic links that you can connect to your own UI. Use these to quickly get up and running with magic links.
Configuration
Email Magic Links require enabling deeplinks in your application. This process is different for Expo managed versus bare (or vanilla) workflows
While the React Native guide contains the full details, below is a summary of the steps required:
iOS Setup
Add the following to AppDelegate.m
// Add the header at the top of the file:
#import <React/RCTLinkingManager.h>
// Add this above '@end':
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
return [RCTLinkingManager application:application openURL:url options:options];
}
If your app is using Universal Links you'll need to add the following code as well:
Add the scheme to your project configuration. The easiest way to do this is with the uri-scheme package by running the following:
npx uri-scheme add myapp --ios
If you want to do it manually, open the project (e.g. SimpleApp/ios/SimpleApp.xcworkspace) in Xcode. Select the project in sidebar and navigate to the info tab. Scroll down to "URL Types" and add a new one. In the new URL type, set the identifier and the URL scheme to your desired URL scheme.
To make sure Universal Links work in your app, you will also need to setup Associated Domains on your server.
If you're using React Navigation within a hybrid app - an iOS app that has both Swift/Objective-C and React Native parts - you may be missing the RCTLinkingIOS subspec in your Podfile, which is installed by default in new React Native projects. To add this, ensure your Podfile looks like the following:
pod 'React', :path => '../node_modules/react-native', :subspecs => [
. . . // other subspecs
'RCTLinkingIOS',
. . .
]
Android Setup
To configure the external linking in Android, you create a new intent in the manifest.
The easiest way to do this is with the uri-scheme package:
npx uri-scheme add myapp --android
If you want to add it manually, open up SimpleApp/android/app/src/main/AndroidManifest.xml, and make the following adjustments:
Set launchMode of MainActivity to singleTask in order to receive intent on existing MainActivity (this is the default, so you may not need to actually change anything).
Add the new <intent-filter> inside the MainActivity entry with a View type action:
Similar to Universal Links on iOS, you can also use a domain to associate the app with your website on Android by Verifying Android App Links. First, you need to configure your AndroidManifest.xml:
Add android:autoVerify="true" to your <intent-filter> entry.
Add your domain's scheme and host in a new <data> entry inside the <intent-filter>
The SDK provides methods that can be used to send magic links and authenticate tokens in the links later.
To call these methods, Email Magic Links must be enabled in the SDK Configuration page of the Stytch dashboard.
Send
The Send method wraps the send Email Magic Link API endpoint. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.
This method is also used when you need to add an email address to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs an email address that does not match one on their Stytch User object, upon successful authentication the new email address will be appended to the emails array. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.
Method parameters
email*string
The email of the user to send the invite magic link to.
Configurationobject
Additional configuration.
Collapse
login_magic_link_urlstring
The URL that users click from the login email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.
signup_magic_link_urlstring
The url the user clicks from the sign-up email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.
login_expiration_minutesint
Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
signup_expiration_minutesint
Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
The Login or create method wraps the login_or_create Email Magic Link API endpoint.
Method parameters
email*string
The email of the user to send the invite magic link to.
Configurationobject
Additional configuration.
Collapse
login_magic_link_urlstring
The url the user clicks from the login email magic link. This should be a url that your app receives and parses and subsequently send an API request to authenticate the magic link and log in the user. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.
signup_magic_link_urlstring
The url the user clicks from the sign-up email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and sign-up the user. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.
login_expiration_minutesint
Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
signup_expiration_minutesint
Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
login_template_idstring
Use a custom template for login emails. By default, it will use your default email template The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
signup_template_idstring
Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
The Authenticate method wraps the authenticate Magic link API endpoint which validates the magic link token passed in. If this method succeeds, the user will be logged in, granted an active session, and the session data will be persisted on device.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook.
Method parameters
token*string
The magic link token from the token query parameter in the URL.
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The React Native SDK provides methods for creating, storing, and authenticating password based users, as well as support for account recovery (password reset) and account deduplication with passwordless login methods.
Methods
The SDK provides methods that can be used to create and authenticate users with a password authentication factor.
To call these methods, Passwords must be enabled in the SDK Configuration page of the Stytch dashboard.
Create
The create method wraps the create Password API endpoint.
email*string
The email of the new user.
password*string
The password for the new user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The authenticate method wraps the authenticate Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session data will be persisted on device.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook.
email*string
The email of the user.
password*string
The password of the user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
The resetByEmailStart method wraps the reset_by_email_start Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session data will be persisted on device.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook.
email*string
The email of the user that requested the password reset.
Configurationobject
Additional configuration.
Collapse
reset_password_redirect_urlstring
The url that the user clicks from the password reset email to finish the reset password flow. This should be a url that your app receives and parses before showing your app's reset password page. After the user submits a new password to your app, it should send an API request to complete the password reset process. If this value is not passed, the default reset password redirect URL that you set in your Dashboard is used. If you have not set a default reset password redirect URL, an error is returned.
login_redirect_urlstring
The url that the user clicks from the password reset email to skip resetting their password and directly login. This should be a url that your app receives, parses, and subsequently sends an API request to the magic link authenticate endpoint to complete the login process without reseting their password. If this value is not passed, the login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.,
reset_password_expiration_minutesint
Set the expiration for the password reset, in minutes. By default, it expires in 30 minutes. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
reset_password_template_idstring
Use a custom template for password reset emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Passwords - Password reset.
The resetByEmail method wraps the reset_by_email Password API endpoint. If this method succeeds, the user will be logged in, granted an active session, and the session data will be persisted on device.
You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook.
password*string
The new password for the user.
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
This method allows you to check whether or not the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password. All passwords must pass the strength requirements to be accepted as valid.
The strengthCheck method wraps the strength_check Password API endpoint.
password*string
The password to strength check.
emailstring
The email associated with the password. Provide this for a more accurate strength check.
Biometric authentication enables your users to leverage their devices' built-in biometric authenticators such as FaceID and TouchID for quick and seamless login experiences.
Configuration
Biometrics requires importing native modules into your React Native or Expo app. If you are using Expo, you may need to review using native modules in the Expo docs.
After installing the latest version of @stytch/react-native or @stytch/react-native-expo, you'll also need to install the latest version of @stytch/react-native-modules. You'll then need to run pod install from the ios folder in order to install the native modules required for biometrics.
Stytch's Biometrics product supports iOS 13.0+ and Android M+
Important: When testing your biometrics implementation with an iOS emulator, you must use iOS version 13 or 14. The minimum target for the Stytch SDKs is iOS 13.0, and biometrics do not work on emulators running iOS 15. This should not be an issue on real devices for testing and production.
Methods
The SDK provides methods that can be used to authenticate users with biometric factors. Biometric factors must first be added to an existing user, and then later used as a primary or secondary authentication factor. To call these methods, Biometrics must be enabled in the SDK Configuration page of the Stytch dashboard.
Register
If an active session is present, this method will add a biometric registration for the current user. The
user will later be able to start a new session with biometrics or use biometrics as an additional
authentication factor.
Method parameters
Options*object
Configuration options
Collapse
prompt*string
The text rendered when raising the biometric prompt
cancelButtonTextstring
The text rendered on the cancel button when raising the biometric prompt. Defaults to "Cancel".
allowDeviceCredentialsboolean
Allows user to enter their device credentials (e.g. PIN code) as a fallback for failed biometric authentication. If this is set to false on registration, authentication will not be allowed to enable fallback to device credentials.
allowFallbackToCleartextboolean
Allows Android devices without access to Keystore to register biometrics. The private key data will be stored as cleartext in the application sandbox.
Learn more about the security implications of this behavior in this section.
If a valid biometric registration exists, this method confirms the current device owner via the device's
built-in biometric reader and returns a session object by either starting a new session or adding a
biometric factor to an existing session.
Method parameters
Options*object
Configuration options
Collapse
prompt*string
The text rendered when raising the biometric prompt
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
cancelButtonTextstring
The text rendered on the cancel button when raising the biometric prompt. Defaults to "Cancel".
allowDeviceCredentialsboolean
Allows user to enter their device credentials (e.g. PIN code) as a fallback for failed biometric authentication. This will fail if the biometric factor was not registered with allowDeviceCredentials set to true.
Indicates whether or not the Keystore is available on the device. This will always return true for iOS
devices. A percentage of Android devices will return false. To learn more about the implications of the Android Keystore being unavailable, read our Android Keystore resource.
Indicates if there is an existing biometric registration on device. This method can be used to determine
whether or not to show biometric login or registration options.
There was an error with the biometric sensor on the device. This usually means that the biometric sensor is currently unavailable for use.
device_credentials_not_allowed
This means that allowDeviceCredentials was set to false in register(), but allowDeviceCredentials was set to true in authenticate(). Consider changing these parameters to be the same.
device_hardware_error
The device's hardware does not support biometrics. This might be because the hardware is unavailable for use, or there is a security vulnerability with the hardware.
internal_error
An internal error has occurred. Please contact Stytch if this occurs.
key_invalidated
The biometrics enrollment on the device has changed, so biometric authentication cannot use the current registration. Try deleting the registration and authenticating again.
keystore_unavailable
The Android keystore is unavailable on the device. Learn more about the Android Keystore here.
no_biometrics_enrolled
No biometric factor is enrolled on the device. Consider encouraging the user to enroll in biometrics on their device.
no_biometrics_registration
No valid biometrics registration exists on the device. Please use the register method to create a new biometric registration.
session_expired
There is currently no valid session token. Consider encouraging the user to log in.
user_cancellation
The user canceled the biometric prompt. Consider providing other methods of authentication, and a way for the user to return to the biometric prompt.
user_locked_out
The user has been locked out from authentication using biometrics due to too many failed attempts. Consider providing other methods of authentication.
Users
Once a user has successfully logged in, the SDK can be used to view and manage that user's information, add additional authentication factors, or delete factors that are no longer used.
Methods
To call these methods, Manage user data must be enabled in the SDK Configuration page of the Stytch dashboard.
Get user
The SDK provides two methods for getting a user. The recommended approach is to use the synchronous method, user.getSync, and listen to changes with the user.onChange method.
If logged in, the user.getSync method returns the cached user object. Otherwise it returns null. This method does not refresh the user's data. The @stytch/react-native and @stytch/react-native-expo libraries provide the useStytchUser hook that implements these methods for you to easily access the user and listen for changes.
The user.onChange method takes in a callback that gets called whenever the user object changes. It returns an unsubscribe method for you to call when you no longer want to listen for such changes.
The asyncronous method, user.get, wraps the get user endpoint. It fetches the user's data and refreshes the cached object if changes are detected. The Stytch SDK will invoke this method automatically in the background, so you probably won't need to call this method directly.
Example
import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react-native';
export const Home = () => {
const stytchUser = useStytchUser();
return stytchUser ? (
<p>Welcome, {stytchUser.name.first_name}</p>
) : (
<p>Log in to continue!</p>
);
};
Update user
Wraps Stytch's update user endpoint. Use this method to change the user's name, untrusted metadata, and attributes.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Method parameters
nameobject
The name of the user. If at least one name field is passed, all name fields will be updated.
Collapse
first_namestring
The first name of the user. Replaces an existing first name, if it exists.
middle_namestring
The middle name(s) of the user. Replaces an existing middle name, if it exists.
last_namestring
The last name of the user. Replaces an existing last name, if it exists.
untrusted_metadataobject
The untrusted_metadata field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and cannot be used to store critical information. See the Metadata reference for complete field behavior details.
Wraps Stytch's delete authentication factors family of endpoints and can be used to remove factors from a user.
These methods cannot be used to remove all factors from a user. A user must have at least one email, phone number, or OAuth provider associated with their account at all times, otherwise they will not be able to log in again.
You can listen for successful user updates anywhere in the codebase with the stytch.user.onChange() method or useStytchUser() hook.
Note: If a user has enrolled another MFA method, this method will require MFA. See the Multi-factor authentication section for more details.
Method parameters
method_id*string
ID of the email, phone number, or WebAuthn registeration to be deleted.
The SDK may be used to check whether a user has a cached session, view the current session, refresh the session, and revoke the session. To authenticate a session on your backend, you must use either the Stytch API or a Stytch server-side library.
Methods
Get session
The SDK provides the session.getSync method to retrieve the current session. The session.onChange method can be used to listen to session changes.
If logged in, the session.getSync method returns the cached session object. Otherwise it returns null. The @stytch/react-native and @stytch/react-native-expo libraries provide the useStytchSession hook that implements these methods for you to easily access the session and listen for changes.
The session.onChange method takes in a callback that gets called whenever the user object changes. It returns an unsubscribe method for you to call when you no longer want to listen for such changes.
Wraps Stytch's authenticate Session endpoint and validates that the session issued to the user is still valid. The SDK will invoke this method automatically in the background. You probably won't need to call this method directly. It's recommended to use session.getSync and session.onChange instead.
Method parameters
Configuration*object
Additional configuration.
Collapse
session_duration_minutes*int
Set the session lifetime to be this many minutes from now. This will return both an opaque session_token and session_jwt for this session, which will automatically be stored in the browser cookies. The session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will be automatically refreshed by the SDK in the background over time.
This value must be a minimum of 5 and may not exceed the maximum session duration minutes value set in the SDK Configuration page of the Stytch dashboard.
A successful authentication will continue to extend the session this many minutes.
When a user registers a biometric factor with Stytch, our SDKs rely on the device keystore to securely store sensitive data associated with the authentication factor.
Unfortunately, Android KeyStore has had significant functionality and reliability issues throughout its lifespan in the Android ecosystem. Not all devices that support biometrics have suitable Keystore implementations that can be relied on.
The official Tink documentation references this instability (1, 2) and they have provided developers with a mechanism to ensure the device you're operating will not encounter implementation problems (3).
If KeyStore is found to be unreliable, this code will fall back to storing sensitive information in the application sandbox, as opposed to the KeyStore. This is not itself a security vulnerability, as the Android platform enforces access barriers between applications to prevent unauthorized access to your application's private data.
That said, this method comes with less security guarantees than using KeyStore, such as protecting the data in the event of a privilege escalation in Android. There are some things you should watch out for when developing an application that allows this fallback.
The biggest issue which would potentially expose your application's sandbox data is writing insecure IPC (inter-process communication). Developers can accidentally create an arbitrary file read vulnerability by misusing Android IPC (4), or by writing sensitive information to public storage (sdcard). Be extra cautious with any functionality that accepts arbitrary file paths as arguments, which may allow an attacker to redirect the flow of data to an area they can access it.