React Native sessions and access - Polygon Developer Docs

An active session binds the local credential to one selected wallet. Authentication can return several wallets, but omsWallet.wallet has one active wallet at a time.

Read and restore session state

The native SDK persists the session. Create OMSWallet with the same publishable key when the app starts; the constructor creates the native client and restores the saved session before it returns. On iOS, when the app launches in the background while the device is locked, the keychain cannot be read yet; the session is restored once the device is unlocked, and onSessionChange then reports a signedIn change.

const activeWallet = omsWallet.wallet.activeWallet
const session = omsWallet.wallet.session

if (activeWallet && session) {
  console.log('Restored wallet:', activeWallet.type, activeWallet.address)
  console.log('Session expires:', session.expiresAt)
  console.log('Authentication:', session.auth)
}

wallet.activeWallet and wallet.session are read synchronously from the native SDK, so they are current as soon as a sign-in or wallet change returns. They return the same frozen objects until the active wallet or session changes.

activeWallet is the active WalletAccount, with id, type, address, optional reference, and keyOrigin, or undefined when signed out. Check type before passing the address to family-specific code.
session is an OMSWalletSession with the current expiresAt and the auth metadata. It is defined exactly when activeWallet is.
Email auth metadata is { type: 'email', email }. OIDC metadata is { type: 'oidc', flow, issuer, provider, providerLabel, email }, with optional provider fields.

Keep your UI in sync

A session stays active while it is used. It ends after about 10 days without use, or at the lifetime requested at sign-in: 180 days by default (DEFAULT_SESSION_LIFETIME_SECONDS, also the maximum). Pass a shorter sessionLifetimeSeconds at sign-in for a hard limit. session.expiresAt is the current expiry, and the SDK keeps it up to date. When expiresAt passes, a session past its requested lifetime ends at once. Otherwise the SDK asks the wallet API, once the app is in the foreground, and reports expired only if the session ended. Protected operations on an ended session throw OMSWalletError with code OMS_SESSION_EXPIRED. onSessionChange calls your listener after every change of activeWallet or session, and returns a function that removes it:

const unsubscribe = omsWallet.wallet.onSessionChange((event) => {
  render(event.activeWallet, event.session)

  if (event.reason === 'expired') {
    showSignIn(event.expiredSession.session.auth)
  }
})
render(omsWallet.wallet.activeWallet, omsWallet.wallet.session)

// During cleanup
unsubscribe()

`reason`	Meaning
`signedIn`	A sign-in made a wallet active
`walletChanged`	Another wallet of the same sign-in became active
`expiryUpdated`	`session.expiresAt` moved; safe to ignore unless you show it
`signedOut`	The session ended without expiring, for example `signOut()`
`expired`	The session expired; `expiredSession` has its wallet and authentication for signing in again

A listener added while signed out first receives the last expired change, until a sign-in starts or the user signs out. In React, useSyncExternalStore keeps a component in sync:

import { useCallback, useSyncExternalStore } from 'react'

function useOMSWalletSession(wallet: OMSWallet['wallet']) {
  const subscribe = useCallback(
    (onChange: () => void) => wallet.onSessionChange(onChange),
    [wallet],
  )
  const activeWallet = useSyncExternalStore(subscribe, () => wallet.activeWallet)
  const session = useSyncExternalStore(subscribe, () => wallet.session)
  return { activeWallet, session }
}

Request timeouts and the signing key

Requests signed with the session go one at a time and fail with OMS_REQUEST_FAILED after 30 seconds, counting the time spent waiting behind other requests. A transaction that times out after it was sent fails with OMS_TRANSACTION_EXECUTION_UNCONFIRMED: check its status before sending it again. On an iOS device, the session signing key is generated in the Secure Enclave and cannot be exported. If the Secure Enclave cannot create it, sign-in fails with OMS_STORAGE_ERROR. Android keeps the key in the Android Keystore.

List and activate wallets

An access credential can have multiple wallets. useWallet changes the selected wallet for the active session:

const wallets = await omsWallet.wallet.listWallets()
const selected = wallets[0]

if (selected !== undefined) {
  const active = await omsWallet.wallet.useWallet(selected.id)
  console.log(active.wallet.address, active.wallet.keyOrigin)
}

Create and activate another wallet with an optional application reference:

const active = await omsWallet.wallet.createWallet({
  reference: 'savings',
})

console.log(active.wallet.id, active.wallet.address)

Wallet listing, switching, and creation require an active credential. They do not repeat authentication. Create a Solana or Tron wallet by setting walletType:

const solana = await omsWallet.wallet.createWallet({
  walletType: 'solana',
  reference: 'solana-primary',
})

const tron = await omsWallet.wallet.createWallet({
  walletType: 'tron',
  reference: 'tron-primary',
})

Each call activates the wallet it creates, so the second call leaves the Tron wallet active.

Claim a preallocated wallet

A completed sign-in result lists, in claimableWallets, the wallets your project preallocated for the user’s email that the sign-in did not claim. See authentication for how wallets become claimable. Claim one with claimWallet:

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

const [claimable] = result.claimableWallets
if (claimable) {
  const active = await omsWallet.wallet.claimWallet(claimable.id)
  console.log('Claimed:', active.wallet.type, active.wallet.address)
}

claimWallet requires an active session and makes the claimed wallet active, like useWallet. A pending manual selection must use selection.claimAndSelectWallet instead.

Import and activate a wallet

const imported = await omsWallet.wallet.importWallet({
  type: 'ethereum',
  privateKey: '0x...', // Supply the private key from your secure migration flow.
  reference: 'imported-wallet',
})

console.log(imported.wallet.keyOrigin)

Ethereum and Tron imports (type: 'tron') accept 32 raw bytes or 64 hexadecimal digits with an optional 0x prefix. Solana imports accept a 32-byte seed or 64-byte keypair as raw bytes, or the base58 encoding of either. The native SDK encrypts the key locally for the attested import transport and does not persist the plaintext key. Returned wallets identify keyOrigin as 'enclave' or 'imported'. Attestation failures reject with SDK error code OMS_ATTESTATION_VERIFICATION_FAILED. Importing a key whose address is already imported rejects with OMS_WALLET_ADDRESS_ALREADY_IMPORTED.

Development uses Nitro debug-mode attestation. Use only disposable test keys in Development. Staging and Production verify against SDK-pinned enclave measurements.

Issue a wallet ID token

A wallet ID token is short-lived proof for the currently active wallet. It is not the provider ID token used to authenticate and it is not the access credential that authorizes wallet API calls.

const walletIdToken = await omsWallet.wallet.getIdToken({
  ttlSeconds: 300,
  customClaims: {
    purpose: 'backend-session',
  },
})

Send the token to your backend over HTTPS and verify it there. See backend wallet verification.

Inspect access grants

Access grants authorize wallet operations and have their own credential IDs and expiry timestamps. A grant has type: 'direct' or type: 'remote'; remote grants also include a session ID, display metadata, and bounded smart-session grants. isCaller identifies the credential currently authorizing the list request. For a short list:

const grants = await omsWallet.wallet.listAccess({
  pageSize: 20,
})

for (const grant of grants) {
  console.log(
    grant.credentialId,
    grant.expiresAt,
    grant.isCaller
  )
  if (grant.type === 'remote') {
    console.log(grant.sessionId, grant.metadata, grant.grants)
  }
}

Iterate every page when you need the complete list:

for await (const page of omsWallet.wallet.listAccessPages({ pageSize: 20 })) {
  for (const grant of page.grants) {
    console.log(grant.credentialId)
  }
}

Use listAccessPage when your UI owns cursor pagination. Omit cursor for the first page, then pass the returned cursor when it is defined:

const firstPage = await omsWallet.wallet.listAccessPage({ pageSize: 20 })
const cursor = firstPage.page?.cursor

const nextPage =
  cursor === undefined
    ? undefined
    : await omsWallet.wallet.listAccessPage({ pageSize: 20, cursor })

Revoke access safely

Check isCaller before revocation. Revoking the caller removes the credential being used for the request and can end the current app’s ability to perform protected operations.

const grants = await omsWallet.wallet.listAccess({ pageSize: 100 })
const target = grants.find((grant) => !grant.isCaller)

if (target === undefined) {
  throw new Error('Credential not found')
}

await omsWallet.wallet.revokeAccess({
  credentialId: target.credentialId,
  sessionId: target.type === 'remote' ? target.sessionId : undefined,
})

For a remote grant, sessionId is required and revokes exactly that session.

Authorize remote access

Remote access grants are bounded EVM smart sessions. Inspect the remote credential and show its returned metadata to the wallet owner before requesting approval: This example uses Polygon Amoy. Grant limits are raw EVM base-unit amounts. A native-transfer limit is cumulative, so 1000000000000000 wei authorizes up to 0.001 POL across the session.

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

const credentialId = 'REMOTE_CREDENTIAL_ID'
const metadata = await omsWallet.wallet.inspectRemoteCredential({ credentialId })

// Render the returned metadata in your consent UI and continue only after approval.
console.log(metadata.appName, metadata.appUrl)

const session = await omsWallet.wallet.authorizeRemoteAccess({
  credentialId,
  network: Networks.amoy,
  expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
  grants: [
    {
      kind: 'nativeTransfer',
      to: '0x1111111111111111111111111111111111111111',
      // Cumulative 0.001 POL limit in wei.
      limit: '1000000000000000',
    },
  ],
})

const details = await omsWallet.wallet.getRemoteAccessSession({
  sessionId: session.sessionId,
})
const usage = await omsWallet.wallet.getRemoteAccessSessionUsage({
  sessionId: session.sessionId,
  network: Networks.amoy,
})

WaaS caps the requested session expiry at the remote credential’s expiry. Backend credential registration and remote execution are outside the React Native SDK; implement them with the TypeScript SDK’s backend smart sessions guide.

Sign out

await omsWallet.wallet.signOut()

Sign-out clears the active local wallet session. It does not revoke other credentials. Use revokeAccess to remove access from another credential.