React Native authentication - Polygon Developer Docs

Authentication establishes an access credential. Wallet selection then activates a wallet and completes the wallet session. Reuse the single omsWallet instance created in the quickstart throughout every flow.

OIDC ID token

When your host app’s provider integration returns an OIDC ID token, pass that token directly to OMS Wallet. The OMS Wallet SDK validates the token and establishes the wallet credential; it does not acquire the provider token.

const result = await omsWallet.wallet.signInWithOidcIdToken({
  idToken,
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  provider: 'google',
  providerLabel: 'Google',
})

if (result.type === 'walletSelected') {
  console.log('Active wallet:', result.wallet.type, result.wallet.address)
}

idToken above is the value returned by your app’s native provider code. Configure that provider to issue the token for the same client ID passed as audience. Sign-in requests a 180-day session by default (DEFAULT_SESSION_LIFETIME_SECONDS). Set sessionLifetimeSeconds to an integer from 1 through 15,552,000 (MAX_SESSION_LIFETIME_SECONDS) for a shorter hard limit; an invalid value rejects with OMS_VALIDATION_ERROR before any request. A session also ends after about 10 days without use. See sessions and access.

Authenticate with email OTP

Email authentication has a request and completion step:

await omsWallet.wallet.startEmailAuth({
  email: 'user@example.com',
  sessionLifetimeSeconds: 604800,
})

const result = await omsWallet.wallet.completeEmailAuth({
  code: '123456',
})

if (result.type === 'walletSelected') {
  console.log('Active wallet:', result.wallet.type, result.wallet.address)
}

The requested session lifetime belongs on startEmailAuth, not completeEmailAuth.

Authenticate with an OIDC redirect

Use redirect authentication when the provider integration does not supply an ID token. Fixed OMS relay configurations are available for Google and Apple:

import { OmsRelayOidcProviders } from '@polygonlabs/oms-wallet-react-native'

const callbackUri = 'com.example.app://auth/callback'

const started = await omsWallet.wallet.startOidcRedirectAuth({
  provider: OmsRelayOidcProviders.google,
  omsRelayReturnUri: callbackUri,
})

The start call also accepts loginHint, sessionLifetimeSeconds, and walletSelection. Leave wallet selection undefined for the automatic default. Open started.authorizationUrl in the platform authentication browser, then pass its returned URL to the SDK:

const callback = await omsWallet.wallet.handleOidcRedirectCallback({
  callbackUrl,
})

if (
  callback.type === 'completed' &&
  callback.result.type === 'walletSelected'
) {
  console.log('Active wallet:', callback.result.wallet.address)
}

An unrelated URL returns notOidcRedirectCallback; a callback without stored pending auth returns noPendingAuth. Provider failures reject with OMSWalletError rather than returning another callback result variant.

Open the authentication browser

Bare React Native and Expo use different browser dependencies:

Bare React Native
Expo

npm install react-native-inappbrowser-reborn
npx pod-install

import { InAppBrowser } from 'react-native-inappbrowser-reborn'

const browser = await InAppBrowser.openAuth(
  started.authorizationUrl,
  callbackUri
)

if (browser.type === 'success') {
  await omsWallet.wallet.handleOidcRedirectCallback({
    callbackUrl: browser.url,
  })
}

npx expo install expo-web-browser

import * as WebBrowser from 'expo-web-browser'

const browser = await WebBrowser.openAuthSessionAsync(
  started.authorizationUrl,
  callbackUri
)

if (browser.type === 'success') {
  await omsWallet.wallet.handleOidcRedirectCallback({
    callbackUrl: browser.url,
  })
}

Add expo-web-browser to the plugins array in the Expo app configuration, set the app scheme, and rebuild the development client after changing native configuration.

Configure callbackUri in the app’s native deep-link configuration.

Configure the app callback

For a bare Android app, add a browsable intent filter to the activity that receives the callback. Keep launchMode="singleTask" so an existing activity receives warm links:

<activity
  android:name=".MainActivity"
  android:exported="true"
  android:launchMode="singleTask">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="com.example.app"
      android:host="auth"
      android:pathPrefix="/callback" />
  </intent-filter>
</activity>

For a bare iOS app, register com.example.app under CFBundleURLTypes in Info.plist. Expo generates both native configurations from the scheme field:

{
  "expo": {
    "scheme": "com.example.app",
    "plugins": ["expo-web-browser"]
  }
}

Handle links delivered outside the authentication browser

The authentication-browser result covers the normal return. If the operating system instead delivers the callback as an app link, obtain warm links from React Native’s Linking.addEventListener('url', ...) and cold-start links from Linking.getInitialURL(), then pass the URL directly to handleOidcRedirectCallback. Route each URL once; a repeated matching callback returns noPendingAuth after the first attempt is consumed.

Use a custom OIDC provider

Use CustomOidcProviderConfig only when your project owns the provider configuration. providerRedirectUri must exactly match a URI registered with the provider.

import type { CustomOidcProviderConfig } from '@polygonlabs/oms-wallet-react-native'

const provider: CustomOidcProviderConfig = {
  issuer: 'https://issuer.example.com',
  clientId: 'YOUR_OIDC_CLIENT_ID',
  authorizationUrl: 'https://issuer.example.com/oauth2/authorize',
  providerRedirectUri: 'com.example.app://auth/callback',
  scopes: ['openid', 'email', 'profile'],
  authMode: 'auth-code-pkce',
}

const started = await omsWallet.wallet.startOidcRedirectAuth({
  provider,
})

Use authorizeParams on the start call for per-attempt authorization parameters.

Select a wallet manually

Request manual selection only when your app provides its own wallet picker:

const result = await omsWallet.wallet.completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
})

if (result.type === 'walletSelection') {
  const selection = result.pendingSelection
  const existingWallet = selection.wallets[0]
  const activeWallet = existingWallet
    ? await selection.selectWallet(existingWallet.id)
    : await selection.createAndSelectWallet('primary')

  console.log('Active wallet:', activeWallet.wallet.address)
}

Use the methods on pendingSelection to finish the same authentication attempt. selection.claimableWallets lists preallocated wallets of the requested type, which selection.claimAndSelectWallet(walletId) claims and activates. The same walletSelection option is available for ID-token and redirect authentication.

Choose a wallet type

Sign-in activates an Ethereum wallet by default. Pass walletType: 'solana' or walletType: 'tron' to completeEmailAuth, signInWithOidcIdToken, or the redirect provider configuration to select or create a wallet of that type instead.

Claim a preallocated wallet

Your project can preallocate a receive-only wallet for a user’s email address through the OMS API, for example to fund it before the user signs in. When the user signs in and proves that email, with email OTP or an OIDC provider that reports a verified email, the wallet is claimable. Claiming makes the user its owner and lets the session sign with it. Sign-in is the only place claimable wallets are reported; listWallets includes a wallet only after it is claimed.

Automatic selection claims a claimable wallet of the requested type when the user owns none of that type. If the claim fails, sign-in fails; the SDK does not create a wallet instead.
result.claimableWallets on a completed sign-in lists the claimable wallets of every type that the sign-in did not claim. Claim one later with claimWallet.
selection.claimableWallets on a pending manual selection lists the claimable wallets of the requested type. selection.claimAndSelectWallet accepts only those IDs.

A rejected claim, for a wallet that is not allocated to the user’s verified email or was already claimed, rejects with OMSWalletError with code OMS_REQUEST_FAILED, status 404, and upstreamError.name 'AccountNotFound'. The active wallet and the pending selection are unchanged.

​OIDC ID token

​Authenticate with email OTP

​Authenticate with an OIDC redirect

​Open the authentication browser

​Configure the app callback

​Handle links delivered outside the authentication browser

​Use a custom OIDC provider

​Select a wallet manually

​Choose a wallet type

​Claim a preallocated wallet