Authentication & Sign-In

New Expensify supports multiple authentication methods to provide a secure and flexible sign-in experience.

Magic Code

Email or SMS code-based authentication

SSO

Google, Apple, and Microsoft sign-in

SAML

Enterprise single sign-on

Getting Started

Enter Your Email or Phone Number

On the sign-in page, enter your email address or phone number:

src/pages/signin/LoginForm/BaseLoginForm.tsx

// The login form accepts both email and phone numbers
const phoneLogin = appendCountryCode(
  getPhoneNumberWithoutSpecialChars(loginTrim), 
  countryCode
);
const parsedPhoneNumber = parsePhoneNumber(phoneLogin);

if (!Str.isValidEmail(loginTrim) && !parsedPhoneNumber.possible) {
  // Show appropriate error message
}

Phone numbers are automatically formatted with your country code.

Receive Your Magic Code

After entering your login, New Expensify will:

Check if your account exists
Determine if SAML is required for your domain
Send a magic code to your email or phone

src/libs/actions/Session/index.ts

function beginSignIn(email: string) {
  const optimisticData: OnyxUpdate[] = [
    {
      onyxMethod: Onyx.METHOD.MERGE,
      key: ONYXKEYS.ACCOUNT,
      value: {
        ...CONST.DEFAULT_ACCOUNT_DATA,
        isLoading: true,
        loadingForm: 'login',
      },
    },
  ];
  
  API.write(WRITE_COMMANDS.BEGIN_SIGN_IN, { email }, {
    optimisticData,
    successData,
    failureData,
  });
}

Enter the Magic Code

Check your email or SMS for the magic code and enter it to complete sign-in.The validate code form handles:

Magic code validation
Two-factor authentication (if enabled)
Recovery code entry

Complete Authentication

Once validated, you’ll be signed in and redirected to the app.

SSO Authentication

New Expensify supports sign-in with Google and Apple accounts.

Google Sign-In
Apple Sign-In
SAML/Enterprise SSO

Google Authentication

src/pages/signin/LoginForm/BaseLoginForm.tsx

<GoogleSignIn
  onPress={handleSignIn}
  onPointerDown={handleSignIn}
/>

Google sign-in is available on all platforms and uses the @react-native-google-signin/google-signin package.

What happens during Google sign-in:

User clicks the Google sign-in button
Google OAuth flow opens in a browser/modal
User authenticates with Google
Google returns an authentication token
New Expensify validates the token and creates/signs into the account

Apple Authentication

src/pages/signin/LoginForm/BaseLoginForm.tsx

<AppleSignIn
  onPress={handleSignIn}
  onPointerDown={handleSignIn}
/>

Apple sign-in uses the @invertase/react-native-apple-authentication package and is available on iOS, macOS, and web.

Apple sign-in flow:

User taps the Apple sign-in button
Apple authentication modal appears
User authenticates with Face ID/Touch ID/Password
Apple returns user credentials
Account is created or signed in

SAML Authentication

For enterprise customers with SAML configured:

src/pages/signin/SignInPage.tsx

// If SAML is required, automatically redirect to SAML sign-in
const shouldInitiateSAMLLogin = 
  hasAccount && 
  hasLogin && 
  isSAMLRequired && 
  !hasInitiatedSAMLLogin && 
  !!account.isLoading;

if (shouldInitiateSAMLLogin) {
  setHasInitiatedSAMLLogin(true);
  Navigation.navigate(ROUTES.SAML_SIGN_IN);
}

SAML Configuration:

Configured at the domain level by workspace admins
Can be required (all users must use SAML) or optional
Users are redirected to their identity provider for authentication

SAML Sign-In Flow:

User enters their email
System detects SAML is required for the domain
User is redirected to the identity provider (e.g., Okta, Azure AD)
User authenticates with their enterprise credentials
Identity provider redirects back to New Expensify
User is signed in

When SAML is required, magic codes and SSO buttons are not available.

Two-Factor Authentication (2FA)

Add an extra layer of security to your account with two-factor authentication.

Setting Up 2FA

Navigate to Security Settings

Go to Settings → Security → Two-factor authentication

Enable 2FA

Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
Enter the 6-digit code from your authenticator app
Save your recovery codes in a safe place

Verify Setup

The next time you sign in, you’ll be prompted for your authenticator code after entering your magic code.

When 2FA is enabled:

src/pages/signin/SignInPage.tsx

// After magic code validation, check if 2FA is required
const isTwoFactorStage = 
  account?.requiresTwoFactorAuth && 
  !!credentials?.validateCode;

if (isTwoFactorStage) {
  welcomeText = isUsingRecoveryCode 
    ? translate('validateCodeForm.enterRecoveryCode') 
    : translate('validateCodeForm.enterAuthenticatorCode');
}

Enter Magic Code

First, enter the magic code sent to your email/phone

Enter Authenticator Code

Then, enter the 6-digit code from your authenticator app

Alternative: Use Recovery Code

If you don’t have access to your authenticator app, you can use one of your recovery codes instead.

Each recovery code can only be used once. Generate new codes after using them.

Recovery Codes

Recovery codes are backup codes that can be used when you don’t have access to your authenticator app:

Each code is single-use
You receive 10 codes when setting up 2FA
Store them securely (password manager, printed copy, etc.)
Generate new codes in your security settings

If you lose both your authenticator app and recovery codes, you’ll need to contact support to regain access to your account.

Session Management

New Expensify manages your session securely with authentication tokens.

Session Lifecycle

src/libs/actions/Session/index.ts

// Session data stored in Onyx
let session: Session = {};

Onyx.connect({
  key: ONYXKEYS.SESSION,
  callback: (value) => {
    session = value ?? {};
    
    if (!session.creationDate) {
      session.creationDate = new Date().getTime();
    }
  },
});

Session Properties:

authToken: JWT token for API authentication
authTokenType: Type of auth (normal, anonymous, support)
accountID: Your unique account identifier
email: Your email address
creationDate: When the session was created

Session Expiration

Sessions expire after a period of inactivity:

src/libs/actions/Session/index.ts

function isExpiredSession(sessionCreationDate: number): boolean {
  return new Date().getTime() - sessionCreationDate 
    >= CONST.SESSION_EXPIRATION_TIME_MS;
}

You’ll be automatically signed out when your session expires. Your work is saved, and you can sign back in to continue.

Signing Out

To sign out of your account:

src/libs/actions/Session/index.ts

function signOut(params: {
  autoGeneratedLogin?: string;
  signedInWithSAML?: boolean;
  authToken?: string;
} = {}): Promise<void | Response<never>> {
  Log.info('Flushing logs before signing out', true, {}, true);
  
  const logOutParams: LogOutParams = {
    authToken: params.authToken ?? null,
    partnerUserID: params.autoGeneratedLogin ?? '',
    shouldRetry: false,
    skipReauthentication: true,
  };

  if (params.signedInWithSAML && params.authToken) {
    return callSAMLSignOut(logOutParams, params.authToken);
  }

  return API.makeRequestWithSideEffects(
    SIDE_EFFECT_REQUEST_COMMANDS.LOG_OUT, 
    logOutParams, 
    {}
  );
}

What happens when you sign out:

Local data is cleared (except specific preserved keys)
API call invalidates the session token
You’re redirected to the sign-in page
For SAML users, the identity provider is also logged out

Security Best Practices

Enable 2FA

Add two-factor authentication for enhanced security

Use Strong Passwords

If using email sign-in, ensure your email has a strong password

Keep Recovery Codes Safe

Store 2FA recovery codes securely

Sign Out on Shared Devices

Always sign out when using shared computers

Troubleshooting

Not Receiving Magic Code

If you’re not receiving your magic code:

Check your spam/junk folder
Verify the email address or phone number is correct
Wait a few minutes and try again
Check your SMS delivery settings (for phone login)

Magic codes expire after 10 minutes. Request a new code if needed.

Invalid Magic Code Error

If you’re getting an “Invalid code” error:

Ensure you’re entering the most recent code
Check for typos
Request a new code if the current one is expired
Clear your browser cache and try again

Lost Authenticator Access

If you’ve lost access to your authenticator app:

Use one of your recovery codes to sign in
Once signed in, disable and re-enable 2FA with a new authenticator
If you don’t have recovery codes, contact support

SAML Sign-In Issues

Next Steps

Create a Workspace

Set up your first workspace to start managing expenses

Invite Team Members

Add colleagues to collaborate on expenses

Configure Settings

Customize your account preferences

Security Settings

Manage your 2FA and security options

Introduction

Setup

Authentication & Sign-In

Magic Code

SSO

SAML

Getting Started

SSO Authentication

Two-Factor Authentication (2FA)

Setting Up 2FA

Recovery Codes

Session Management

Session Lifecycle

Session Expiration

Signing Out

Security Best Practices

Enable 2FA

Use Strong Passwords

Keep Recovery Codes Safe

Sign Out on Shared Devices

Troubleshooting

Next Steps

Create a Workspace

Invite Team Members

Configure Settings

Security Settings

Build docs developers (and LLMs) love

Introduction

Setup

​Sign-In Methods

Magic Code

SSO

SAML

​Getting Started

​Basic Sign-In Flow

​SSO Authentication

​Google Authentication

​Apple Authentication

​SAML Authentication

​Two-Factor Authentication (2FA)

​Setting Up 2FA

​2FA Sign-In Flow

​Recovery Codes

​Session Management

​Session Lifecycle

​Session Expiration

​Signing Out

​Security Best Practices

Enable 2FA

Use Strong Passwords

Keep Recovery Codes Safe

Sign Out on Shared Devices

​Troubleshooting

​Next Steps

Create a Workspace

Invite Team Members

Configure Settings

Security Settings

Build docs developers (and LLMs) love

Sign-In Methods

Getting Started

Basic Sign-In Flow

SSO Authentication

Google Authentication

Apple Authentication

SAML Authentication

Two-Factor Authentication (2FA)

Setting Up 2FA

2FA Sign-In Flow

Recovery Codes

Session Management

Session Lifecycle

Session Expiration

Signing Out

Security Best Practices

Troubleshooting

Next Steps