> For the complete documentation index, see [llms.txt](/llms.txt).

# Custom authentication in React Native SDK

Custom authentication lets you integrate your own identity provider, Google with your own Client ID, Firebase, Auth0, AWS Cognito, or any custom JWT issuer, so that the resulting wallet is tied to your user identity rather than to Web3Auth's default verifiers.

note

This is a paid feature and the minimum [pricing plan](https://web3auth.io/pricing.html) to use this SDK in a production environment is the **Growth Plan**. You can use this feature in Web3Auth Sapphire Devnet network for free.

## Prerequisites

Create a **Connection** in the [Authentication tab](https://developer.metamask.io) of your project on the Embedded Wallets dashboard. The dashboard will give you an **Auth Connection ID** which you pass to `connectTo` at sign-in time.

No changes to `web3AuthOptions` are required for custom authentication in v9. The `loginConfig` parameter from v8 has been removed.

## Single connection

Use `AUTH_CONNECTION.CUSTOM` with `authConnectionId` to target a specific connection registered on the dashboard.

**Firebase (JWT)**

The SDK handles the Firebase redirect natively. Obtain the Firebase `idToken` first (using the Firebase JS SDK), then pass it directly to `connectTo`:

```tsx
import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'
import { signInWithPopup, GoogleAuthProvider, getAuth } from 'firebase/auth'

function FirebaseLoginButton() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const login = async () => {
    const auth = getAuth()
    const result = await signInWithPopup(auth, new GoogleAuthProvider())
    const idToken = await result.user.getIdToken(true)

    await connectTo({
      authConnection: AUTH_CONNECTION.CUSTOM,
      authConnectionId: 'w3a-firebase-demo', // Dashboard Connection ID
      idToken,
      extraLoginOptions: { verifierIdField: 'sub' },
    })
  }

  return <Button title="Sign in with Firebase" disabled={loading} onPress={login} />
}

```

**Auth0 (SDK-native)**

For Auth0, the SDK opens Auth0's login page natively, you no longer need `react-native-auth0`:

```tsx
import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'

function Auth0LoginButton() {
  const { connectTo, loading } = useWeb3AuthConnect()

  return (
    <Button
      title="Sign in with Auth0"
      disabled={loading}
      onPress={() =>
        connectTo({
          authConnection: AUTH_CONNECTION.CUSTOM,
          authConnectionId: 'w3a-auth0-demo', // Dashboard Connection ID
          extraLoginOptions: {
            domain: 'https://web3auth.au.auth0.com', // Your Auth0 domain
            verifierIdField: 'sub',
          },
        })
      }
    />
  )
}

```

**Custom Google Client ID**

To use your own Google Client ID instead of Web3Auth's default, create a Google connection on the dashboard:

```tsx
import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'

function GoogleLoginButton() {
  const { connectTo, loading } = useWeb3AuthConnect()

  return (
    <Button
      title="Sign in with Google"
      disabled={loading}
      onPress={() =>
        connectTo({
          authConnection: AUTH_CONNECTION.GOOGLE,
          authConnectionId: 'my-google-connection', // Your dashboard Connection ID
        })
      }
    />
  )
}

```

## Grouped connections (aggregate verifiers)

Grouped connections allow users to sign in through different providers and always receive the same wallet address, as long as the underlying email or user identifier matches. This is useful for "Sign in with Google" and "Sign in with email" mapping to the same wallet.

Configure a **Grouped Connection** on the dashboard, then pass the group ID as `groupedAuthConnectionId` alongside each individual connection's `authConnectionId`:

```tsx
import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'

function GroupedLoginView() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const loginWithGoogle = () =>
    connectTo({
      authConnection: AUTH_CONNECTION.GOOGLE,
      authConnectionId: 'w3a-google', // individual connection
      groupedAuthConnectionId: 'aggregate-sapphire', // grouped connection
    })

  const loginWithEmail = () =>
    connectTo({
      authConnection: AUTH_CONNECTION.CUSTOM,
      authConnectionId: 'w3a-a0-email-passwordless',
      groupedAuthConnectionId: 'aggregate-sapphire', // same group → same wallet
    })

  return (
    <View>
      <Button title="Sign in with Google" disabled={loading} onPress={loginWithGoogle} />
      <Button title="Sign in with Email" disabled={loading} onPress={loginWithEmail} />
    </View>
  )
}

```

Both buttons produce the same wallet address for users whose email matches across providers.

## `connectTo` parameter reference

**Parameters**

| Parameter                  | Required | Description                                                                                                                                                                                                                            |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authConnection`           | Yes      | Authentication method. Pass an `AUTH_CONNECTION.*` constant. Replaces the v8 `loginProvider` field.                                                                                                                                    |
| `authConnectionId?`        | No       | Dashboard Connection ID for the auth connection. Required when using `AUTH_CONNECTION.CUSTOM` or when you have multiple connections of the same type and need to target one specifically. Replaces the v8 `loginConfig[key].verifier`. |
| `groupedAuthConnectionId?` | No       | Dashboard Grouped Connection ID when using grouped (aggregate) connections. Connections sharing the same `groupedAuthConnectionId` produce the same wallet address. Replaces the v8 `loginConfig[key].verifierSubIdentifier`.          |
| `idToken?`                 | No       | A JWT issued by your authentication provider (Firebase, Auth0, Cognito, and so on). Pass this when using `AUTH_CONNECTION.CUSTOM`. The token is sent directly to the SDK instead of opening a browser redirect.                        |
| `extraLoginOptions?`       | No       | Additional OAuth hints passed to the authentication provider. Common fields: `login_hint` (email), `domain` (Auth0 domain), `verifierIdField` (JWT claim to use as the wallet identifier).                                             |
| `redirectUrl?`             | No       | Override the global `redirectUrl` from `web3AuthOptions` for this login call only.                                                                                                                                                     |
| `mfaLevel?`                | No       | Override the global `mfaLevel` for this login call only.                                                                                                                                                                               |
| `curve?`                   | No       | Elliptic curve to use for key generation. Accepts `SUPPORTED_KEY_CURVES.SECP256K1` (EVM) or `SUPPORTED_KEY_CURVES.ED25519` (Solana). Defaults to the chain namespace.                                                                  |
| `sessionTime?`             | No       | Override the global session duration (in seconds) for this login session only.                                                                                                                                                         |
| `dappShare?`               | No       | Custom device share key for MFA-enabled wallets. Required when reconstructing a key with a custom share.                                                                                                                               |
| `appState?`                | No       | Arbitrary state string that is returned in the redirect callback. Useful for restoring application state after the OAuth redirect.                                                                                                     |

**Interface**

```typescript
export interface SdkLoginParams {
  /** Authentication method: use AUTH_CONNECTION.* constants */
  authConnection: AUTH_CONNECTION_TYPE
  /** Dashboard Connection ID; required for AUTH_CONNECTION.CUSTOM */
  authConnectionId?: string
  /** Grouped Connection ID for aggregate verifier flows */
  groupedAuthConnectionId?: string
  /** JWT from your auth provider for custom authentication */
  idToken?: string
  /** Additional OAuth parameters (login_hint, domain, verifierIdField, etc.) */
  extraLoginOptions?: ExtraLoginOptions
  /** Override redirectUrl for this login call */
  redirectUrl?: string
  /** Override MFA level for this login call */
  mfaLevel?: MfaLevelType
  /** Elliptic curve for key generation */
  curve?: SUPPORTED_KEY_CURVES_TYPE
  /** Override session duration for this session */
  sessionTime?: number
  /** Custom device share for MFA-enabled wallets */
  dappShare?: string
  /** Arbitrary app state to restore after redirect */
  appState?: string
}

```

**AUTH_CONNECTION enum**

`AUTH_CONNECTION` replaces the v8 `LOGIN_PROVIDER` enum. Import it from `@web3auth/react-native-sdk`.

| `AUTH_CONNECTION` constant           | Description                                               | v8 `LOGIN_PROVIDER` equivalent      |
| ------------------------------------ | --------------------------------------------------------- | ----------------------------------- |
| `AUTH_CONNECTION.GOOGLE`             | Google OAuth 2.0                                          | `LOGIN_PROVIDER.GOOGLE`             |
| `AUTH_CONNECTION.FACEBOOK`           | Facebook OAuth                                            | `LOGIN_PROVIDER.FACEBOOK`           |
| `AUTH_CONNECTION.APPLE`              | Sign in with Apple                                        | `LOGIN_PROVIDER.APPLE`              |
| `AUTH_CONNECTION.DISCORD`            | Discord OAuth                                             | `LOGIN_PROVIDER.DISCORD`            |
| `AUTH_CONNECTION.TWITTER`            | Twitter / X OAuth                                         | `LOGIN_PROVIDER.TWITTER`            |
| `AUTH_CONNECTION.GITHUB`             | GitHub OAuth                                              | `LOGIN_PROVIDER.GITHUB`             |
| `AUTH_CONNECTION.TWITCH`             | Twitch OAuth                                              | `LOGIN_PROVIDER.TWITCH`             |
| `AUTH_CONNECTION.LINE`               | LINE OAuth                                                | `LOGIN_PROVIDER.LINE`               |
| `AUTH_CONNECTION.KAKAO`              | Kakao OAuth                                               | `LOGIN_PROVIDER.KAKAO`              |
| `AUTH_CONNECTION.LINKEDIN`           | LinkedIn OAuth                                            | `LOGIN_PROVIDER.LINKEDIN`           |
| `AUTH_CONNECTION.WEIBO`              | Weibo OAuth                                               | `LOGIN_PROVIDER.WEIBO`              |
| `AUTH_CONNECTION.WECHAT`             | WeChat OAuth                                              | `LOGIN_PROVIDER.WECHAT`             |
| `AUTH_CONNECTION.EMAIL_PASSWORDLESS` | Magic link / OTP sent to an email address                 | `LOGIN_PROVIDER.EMAIL_PASSWORDLESS` |
| `AUTH_CONNECTION.SMS_PASSWORDLESS`   | OTP sent to a phone number                                | `LOGIN_PROVIDER.SMS_PASSWORDLESS`   |
| `AUTH_CONNECTION.FARCASTER`          | Farcaster protocol sign-in                                | ,                                   |
| `AUTH_CONNECTION.CUSTOM`             | Any custom JWT flow (Firebase, Auth0, Cognito, and so on) | `LOGIN_PROVIDER.JWT`                |

## `extraLoginOptions` field reference

| Field                        | Type      | Description                                                                                                                   |
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `domain?`                    | `string`  | Your identity provider domain (for example, `https://example.auth0.com`).                                                     |
| `login_hint?`                | `string`  | Pre-filled email address for email passwordless flows.                                                                        |
| `verifierIdField?`           | `string`  | The JWT claim to use as the user identifier (typically `sub` or `email`). Must match the setting in the dashboard connection. |
| `isVerifierIdCaseSensitive?` | `boolean` | Whether the verifier ID field comparison is case-sensitive. Default is `true`.                                                |
| `client_id?`                 | `string`  | Client ID of the OAuth application (if different from `clientId` in `web3AuthOptions`).                                       |
| `leeway?`                    | `string`  | Clock skew tolerance in seconds for JWT expiry checks. Maximum `120`.                                                         |
| `scope?`                     | `string`  | Space-separated list of OAuth scopes to request.                                                                              |
| `id_token_hint?`             | `string`  | A previously issued ID token to pass as a hint.                                                                               |
| `redirect_uri?`              | `string`  | Override the redirect URI for the OAuth flow.                                                                                 |