React Native SDK Authentication - Polygon Developer Docs

The React Native SDK supports email OTP, OIDC ID-token auth, and low-level OIDC redirect auth. After auth completes, the SDK can automatically select the first existing wallet of the requested type or create one when needed. Use manual wallet selection when your app should present wallet choices.

Configure

Configure the SDK before using authentication, wallet, signing, transaction, balance, or access APIs.

import { configure } from '@0xsequence/oms-react-native-sdk'

await configure({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  projectId: 'YOUR_PROJECT_ID',
})

Parameters

Parameter	Type	Description
`publishableKey`	`string`	OMS publishable key sent to the native SDKs.
`projectId`	`string`	OMS project ID used for request signing scope and session storage scope.
`environment`	`OmsClientEnvironment` or undefined	Optional override for `walletApiUrl`, `apiRpcUrl`, or `indexerUrlTemplate`.

Returns Returns Promise<void>.

Start Email Auth

Send a one-time code to the user’s email address.

import { startEmailAuth } from '@0xsequence/oms-react-native-sdk'

await startEmailAuth('user@example.com')

Parameters

Parameter	Type	Description
`email`	`string`	Email address that receives the one-time code.

Returns Returns Promise<void>.

Complete Email Auth

Complete the flow with the code entered by the user. Automatic mode selects the first matching wallet or creates one when none exists.

import { completeEmailAuth } from '@0xsequence/oms-react-native-sdk'

const result = await completeEmailAuth({ code: '123456' })

if (result.type === 'walletSelected') {
  console.log('Wallet address:', result.walletAddress)
  console.log('Wallet ID:', result.wallet.id)
}

Use manual wallet selection when the app needs to choose between wallets before activating one.

const result = await completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
  walletType: 'ethereum',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}

Parameters

Parameter	Type	Description
`code`	`string`	One-time code entered by the user.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional wallet session lifetime in seconds.

Returns Returns Promise<OmsCompleteAuthResult>.

Field	Type	Description
`type`	`'walletSelected'` or `'walletSelection'`	Indicates whether a wallet was activated or manual selection is pending.
`walletAddress`	`string` or `null`	Active embedded wallet address in automatic mode.
`wallet`	`OmsWallet` or `null`	Selected or created wallet in automatic mode.
`wallets`	`OmsWallet[]`	Wallets returned by auth completion.
`credential`	`OmsCredentialInfo`	Credential added by auth completion.
`pendingSelection`	`OmsPendingWalletSelection` or undefined	Manual wallet selection helper.

Authenticate with an ID token your app receives from an OIDC provider.

import { signInWithOidcIdToken } from '@0xsequence/oms-react-native-sdk'

const result = await signInWithOidcIdToken({
  idToken: 'OIDC_ID_TOKEN',
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  walletSelection: 'automatic',
  walletType: 'ethereum',
})

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

Parameters

Parameter	Type	Description
`idToken`	`string`	OIDC ID token issued to the app.
`issuer`	`string`	Expected token issuer.
`audience`	`string`	Expected token audience, such as the app’s OIDC client ID.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional wallet session lifetime in seconds.

Returns Returns Promise<OmsCompleteAuthResult>.

OIDC Provider Config

Use OidcProviders.google to build the provider config for Google redirect auth.

import { OidcProviders } from '@0xsequence/oms-react-native-sdk'

const provider = OidcProviders.google({
  clientId: 'YOUR_WEB_CLIENT_ID',
  relayRedirectUri: null,
})

Parameters

Parameter	Type	Description
`clientId`	`string` or undefined	Google OAuth client ID. Defaults to the SDK’s configured Google client ID.
`relayRedirectUri`	`string`, `null`, or undefined	Relay callback URL. Omit it to use the provider default, or pass `null` to redirect directly to the app redirect URI.
`scopes`	`string[]` or undefined	OAuth scopes. Defaults to `openid`, `email`, and `profile`.
`authorizeParams`	`Record<string, string>` or undefined	Extra authorization query parameters.

Returns Returns OidcProviderConfig.

Start OIDC Redirect Auth

Start an OIDC authorization-code PKCE flow. Apps own browser opening and deep-link handling. Use system auth browser UI such as Custom Tabs or ASWebAuthenticationSession, then pass the resulting app-link URL to handleOidcRedirectCallback.

import {
  OidcProviders,
  startOidcRedirectAuth,
} from '@0xsequence/oms-react-native-sdk'

const started = await startOidcRedirectAuth({
  provider: OidcProviders.google({ clientId: 'YOUR_WEB_CLIENT_ID' }),
  redirectUri: 'com.example.app:/oauth/callback',
  walletType: 'ethereum',
})

console.log('Open this URL with system auth UI:', started.authorizationUrl)

Parameters

Parameter	Type	Description
`provider`	`OidcProviderConfig`	OIDC provider config.
`redirectUri`	`string`	App callback URL that receives the provider redirect.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`relayRedirectUri`	`string`, `null`, or undefined	Overrides the provider relay redirect URI.
`authorizeParams`	`Record<string, string>` or `null`	Extra authorization query parameters.
`loginHint`	`string`, `null`, or undefined	Optional OIDC login hint, sent as OAuth `login_hint` for Google providers.

Returns Returns Promise<OmsStartOidcRedirectAuthResult>.

Field	Type	Description
`authorizationUrl`	`string`	Provider authorization URL to open with system auth UI.
`state`	`string`	OIDC state value stored for callback validation.
`challenge`	`string`	Wallet auth challenge used in the OIDC request.

Handle OIDC Redirect Callback

Complete redirect auth after the provider sends the user back to your app.

import { handleOidcRedirectCallback } from '@0xsequence/oms-react-native-sdk'

const result = await handleOidcRedirectCallback({
  callbackUrl: 'com.example.app:/oauth/callback?code=CODE&state=STATE',
  walletSelection: 'manual',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}

Parameters

Parameter	Type	Description
`callbackUrl`	`string`, `null`, or undefined	Full callback URL containing OIDC `code` and `state`.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional wallet session lifetime in seconds.

Returns Returns Promise<OmsOidcRedirectAuthResult>.

Result `type`	Description
`completed`	Redirect auth completed and returned an active wallet.
`walletSelection`	Auth completed and manual wallet selection is pending.
`notOidcRedirectCallback`	The URL was not an OIDC redirect callback for this SDK.
`noPendingAuth`	There is no pending redirect auth flow to complete.
`failed`	Redirect auth failed and includes a `message`.

List Wallets

List wallets available to the authenticated credential.

import { listWallets } from '@0xsequence/oms-react-native-sdk'

const wallets = await listWallets()

for (const wallet of wallets) {
  console.log(wallet.id, wallet.type, wallet.address)
}

Parameters Takes no parameters. Returns Returns Promise<OmsWallet[]>.

Use Wallet

Activate an existing wallet by server-side wallet ID.

import { useWallet } from '@0xsequence/oms-react-native-sdk'

const result = await useWallet('wallet-id')

console.log('Wallet address:', result.walletAddress)

Parameters

Parameter	Type	Description
`walletId`	`string`	Wallet ID returned by auth completion or `listWallets`.

Returns Returns Promise<OmsWalletActivationResult>.

Create Wallet

Create and activate a new wallet for the authenticated user.

import { createWallet } from '@0xsequence/oms-react-native-sdk'

const result = await createWallet({
  walletType: 'ethereum',
  reference: 'main',
})

console.log('New wallet:', result.walletAddress)

Parameters

Parameter	Type	Description
`walletType`	`'ethereum'` or undefined	Wallet type to create. Defaults to `ethereum`.
`reference`	`string`, `null`, or undefined	Optional app-defined wallet reference.

Returns Returns Promise<OmsWalletActivationResult>.

​Configure

​Start Email Auth

​Complete Email Auth

​Sign In With OIDC ID Token

​OIDC Provider Config

​Start OIDC Redirect Auth

​Handle OIDC Redirect Callback

​List Wallets

​Use Wallet

​Create Wallet

Configure

Start Email Auth

Complete Email Auth

Sign In With OIDC ID Token

OIDC Provider Config

Start OIDC Redirect Auth

Handle OIDC Redirect Callback

List Wallets

Use Wallet

Create Wallet