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.walletAddress)
}

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. The requested credential lifetime defaults to one week. Set sessionLifetimeSeconds to an integer from 1 through 2,592,000 seconds when you need another lifetime.

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.walletAddress)
}

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.walletAddress)
}

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.walletAddress)
}

Use the methods on pendingSelection to finish the same authentication attempt. The same walletSelection option is available for ID-token and redirect authentication.

​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