Authentication

The Soundcheck mobile app uses Clerk for authentication, supporting email/password, Google OAuth, and Apple Sign In on supported platforms (not every SSO option appears on every platform).

Overview

Authentication is handled through:

Clerk SDK for session management
JWT tokens for API authentication
SecureStore for token persistence
OAuth flows for social login

Authentication methods

Email/password

Traditional email and password authentication with:

Email verification
Password reset flow
Session management

Google OAuth

“Continue with Google” runs useGoogleSsoFlow (lib/hooks/useGoogleSsoFlow.ts), which picks one of two flows:

Flow	When
Native Google account sheet (`useSignInWithGoogle` from `@clerk/expo/google`, native module from `@clerk/expo-google-signin`)	A native build with the `ClerkGoogleSignIn` module linked and the variables below set. iOS needs the web and iOS client IDs plus a URL scheme that matches the reversed iOS client ID. Android needs the web client ID.
Browser OAuth (`useOAuth({ strategy: 'oauth_google' })`, redirect `soundcheck://oauth-callback`)	Expo Go, a build without the module, missing or mismatched variables, or any native failure other than a cancel or a Clerk API rejection

A cancel in either flow returns quietly. Other failures show copy from lib/errors/userFacingError.ts, never Clerk’s raw text. The native module ships only in a new store build; it cannot go out over the air. The client IDs are public identifiers, not secrets. They come from the EAS environment (or a local .env), never from the repo. app.config.js copies them into extra, where Clerk’s hook and config plugin read them, and appends .apps.googleusercontent.com to a client ID given without it. Without them the app uses the browser flow and never touches the native module.

Variable	Where	Value
`EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`	All EAS environments	The Google Cloud Web application client ID that Clerk’s Google connection uses. Android uses it as the server client ID, and it is the ID token audience.
`EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`	All EAS environments	The Google Cloud iOS client ID for bundle `com.soundchecklive.app`
`EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME`	All EAS environments	The reversed iOS client ID (`com.googleusercontent.apps.<id>`). `app.config.js` adds it to `CFBundleURLTypes`. iOS uses the native sheet only when it is set and matches; without it, iOS uses the browser. A mismatch logs a config warning instead of failing the build.
`GOOGLE_OAUTH_ANDROID_CLIENT_ID`	All EAS environments, build time only (no `EXPO_PUBLIC_` prefix)	The Android OAuth client. The app never reads it: Android’s Credential Manager only takes the web client ID, and Google matches the Android client by package name and signing SHA-1.

The URL scheme gate matters because GoogleSignIn on iOS raises a native exception, which JavaScript cannot catch, when the reversed client ID scheme is missing from the app.

Google Cloud

A Web application OAuth client. Its ID and secret are the custom credentials on Clerk’s Google connection.
An iOS OAuth client for bundle ID com.soundchecklive.app (with the Apple Team ID).
An Android OAuth client for package com.soundchecklive.app with the SHA-1 of the EAS upload keystore (eas credentials -p android). Builds installed from Google Play are re-signed, so add a second Android client with the SHA-1 of the Play app signing key (Play Console → App integrity). A new Android client can take a few hours to start working; until then the app falls back to the browser.

Clerk dashboard (each instance used by dev, qa and prod builds)

SSO connections → Google: enabled, with custom credentials (the web client ID and secret from step 1).
Native applications: register the iOS app (Team ID + bundle ID) and the Android app (package name + SHA-256 fingerprints of the upload and Play signing keys).
Keep soundcheck://oauth-callback in the allowed redirect URLs so the browser fallback keeps working.

EAS environment variables

Set the variables in the table above (plain-text visibility), each matching the Clerk instance behind that environment’s publishable key. Then make a new native build.

Apple Sign In is not offered on every platform:

Platform	Experience
iOS	Native Apple Sign In prompt
Android	Google only on native (`SsoButtons.android.tsx`; no Apple button)
Web (Clerk)	Apple via standard OAuth popup

On iOS and web, post-auth redirects use /(tabs)/events, the Expo Router path for the tab labeled Gigs:

const { startOAuthFlow } = useOAuth({ strategy: 'oauth_apple' });

const handleAppleLogin = async () => {
  const { createdSessionId, setActive } = await startOAuthFlow();
  if (createdSessionId && setActive) {
    await setActive({ session: createdSessionId });
    router.replace('/(tabs)/events'); // Gigs tab
  }
};

Configuration

iOS configuration

Apple Sign In requires iOS entitlements. These are configured in app.config.js:

ios: {
  entitlements: {
    "com.apple.developer.applesignin": ["Default"],
  },
}

The expo-apple-authentication plugin is included automatically.

Clerk dashboard setup

To enable social authentication:

Enable OAuth Providers

Go to Clerk Dashboard
Navigate to User & Authentication → Social Connections
Enable Google and/or Apple

Configure Google OAuth

Create OAuth credentials in Google Cloud Console
Add credentials to Clerk Dashboard
Configure redirect URLs

Configure Apple Sign In

Enable Sign In with Apple in Apple Developer Console
Create Services ID for OAuth
Generate private key
Add credentials to Clerk Dashboard

Apple Sign In requires an Apple Developer account ($99/year).

Token management

How tokens work

┌─────────────────┐
│   User Login    │
│  (via Clerk)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Clerk Session   │
│   Established   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AuthContext    │
│  sets up token  │
│  getter in      │
│  httpClient     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  API Request    │
│  calls getToken()│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Clerk returns  │
│  fresh JWT      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Token added to │
│  Authorization  │
│  header         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Request sent   │
│  to backend     │
└─────────────────┘

Token lifecycle

Generation: Clerk creates a JWT when user signs in
Caching: Token is stored in SecureStore via tokenCache
Retrieval: getToken() returns the current valid token
Refresh: Clerk automatically refreshes expired tokens
Expiration: Tokens expire after 1 hour (configurable in Clerk)

Token format

All authenticated requests include:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Imluc18y...

AuthContext

The AuthContext provides authentication state throughout the app:

// lib/context/AuthContext.tsx
interface AuthContextType {
  user: User | null;
  isSignedIn: boolean;
  isLoaded: boolean;
  isTokenReady: boolean;
  signOut: () => Promise<void>;
}

export function useAuth() {
  return useContext(AuthContext);
}

Provider setup

The AuthProvider must be inside ClerkProvider:

// app/_layout.tsx
<ClerkProvider
  publishableKey={publishableKey}
  tokenCache={tokenCache}
  signInFallbackRedirectUrl="/(tabs)/events" // Gigs tab
  signUpFallbackRedirectUrl="/(tabs)/events" // Gigs tab
>
  <AuthProvider>
    {/* App content */}
  </AuthProvider>
</ClerkProvider>

Error handling

Common OAuth errors

User Cancelled OAuth Flow

This is expected behavior when users cancel authentication:

try {
  await startOAuthFlow();
} catch (error) {
  if (error.code === 'ERR_REQUEST_CANCELED' ||
      error.code === 'user_cancelled_oauth_flow') {
    // Silent - user cancelled, no error message needed
    return;
  }
  // Show error for other cases
  showError('Authentication failed');
}

Invalid Client Error

The Services ID or configuration doesn’t match between Apple and Clerk:

Verify Services ID in Clerk matches Apple Developer Console
Check redirect URLs match exactly
Ensure the Services ID is enabled for Sign In with Apple

Invalid Grant Error

Private key or Team ID mismatch:

Re-enter the private key in Clerk Dashboard
Verify Team ID is correct (10 characters)
Verify Key ID is correct (10 characters)

App Doesn't Open After Auth

OAuth redirect not working:

Verify scheme: "soundcheck" in app.config.js
Rebuild the app with eas build
Check Clerk Dashboard OAuth redirect configuration

Security

Best practices

Never commit secrets - Keep Clerk keys in environment variables
Use SecureStore - Tokens are stored securely in iOS Keychain/Android Keystore
Short-lived tokens - JWT tokens expire, limiting vulnerability window
Automatic refresh - Clerk handles token refresh automatically
Revocable sessions - Sessions can be revoked from Clerk Dashboard

Environment variables

# Required
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

# Not needed in mobile app (server-side only)
# CLERK_SECRET_KEY=sk_test_...

Never include CLERK_SECRET_KEY in mobile app code. It’s only for server-side use.

Testing authentication

Debug checklist

Check token is being sent:
- Open React Native debugger
- Check Network tab
- Verify Authorization: Bearer ... header

Verify user state:

const { user, isSignedIn } = useAuth();
console.log('Auth state:', { user, isSignedIn });

Test with cURL:

TOKEN="eyJhbGciOiJSUzI1NiIs..."
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/api/v1/users/me

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Overview

Authentication methods

Email/password

Google OAuth

Configuration

iOS configuration

Clerk dashboard setup

Token management

How tokens work

Token lifecycle

Token format

AuthContext

Provider setup

Error handling

Common OAuth errors

Security

Best practices

Environment variables

Testing authentication

Debug checklist

Resources

​Overview

​Authentication methods

​Email/password

​Google OAuth

​Native Google sign-in configuration

​Apple sign in

​Configuration

​iOS configuration

​Clerk dashboard setup

​Token management

​How tokens work

​Token lifecycle

​Token format

​AuthContext

​Provider setup

​Error handling

​Common OAuth errors

​Security

​Best practices

​Environment variables

​Testing authentication

​Debug checklist

​Resources

Overview

Authentication methods

Email/password

Google OAuth

Native Google sign-in configuration

Apple sign in

Configuration

iOS configuration

Clerk dashboard setup

Token management

How tokens work

Token lifecycle

Token format

AuthContext

Provider setup

Error handling

Common OAuth errors

Security

Best practices

Environment variables

Testing authentication

Debug checklist

Resources