React Native sessions and access - Polygon Developer Docs

A completed wallet session combines a selected wallet, credential expiry, and authentication metadata. Protected wallet operations require this active session.

Restore the completed session

The native SDK persists completed sessions. Reuse the single OMSWallet instance with the same publishable key when the app starts, then read its state:

const session = await omsWallet.wallet.getSession()

if (session.walletAddress !== undefined) {
  console.log('Restored wallet:', session.walletAddress)
  console.log('Credential expires:', session.expiresAt)
}

OMSWalletSessionState contains:

Field	Type	Meaning
`walletAddress`	`string	undefined`	The selected wallet in a completed session.
`expiresAt`	`string	undefined`	The active credential expiry timestamp.
`auth`	`OMSWalletSessionAuth	undefined`	Email or OIDC authentication metadata.

Email metadata contains type: 'email' and email. OIDC metadata contains type: 'oidc', flow: 'id-token' | 'redirect', issuer, and optional provider, label, and email values. Use getWalletAddress() when you only need the selected address:

const walletAddress = await omsWallet.wallet.getWalletAddress()

Observe expiration

Subscribe where your application owns wallet-session state and remove the subscription during cleanup:

const subscription = omsWallet.wallet.onSessionExpired((event) => {
  console.log('Expired at:', event.expiredAt)
  console.log('Previous wallet:', event.session.walletAddress)
})

// During cleanup
subscription.remove()

The SDK replays the latest expiration event to a listener that subscribes after native expiration. Starting or completing a new authentication flow clears that replay.

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

Create and activate another wallet with an optional application reference:

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

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

Wallet listing, switching, and creation require an active credential. They do not repeat authentication.

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 credentials

Access credentials authorize wallet operations and have their own IDs and expiry timestamps. isCaller identifies the credential currently authorizing the list request. For a short list:

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

for (const credential of credentials) {
  console.log(
    credential.credentialId,
    credential.expiresAt,
    credential.isCaller
  )
}

Iterate every page when you need the complete list:

for await (const page of omsWallet.wallet.listAccessPages({ pageSize: 20 })) {
  for (const credential of page.credentials) {
    console.log(credential.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 credentials = await omsWallet.wallet.listAccess({ pageSize: 100 })
const target = credentials.find(
  (credential) => credential.credentialId === targetCredentialId
)

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

if (target.isCaller) {
  throw new Error('Sign out or reauthenticate before revoking this credential')
}

await omsWallet.wallet.revokeAccess(target.credentialId)

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.

​Restore the completed session

​Observe expiration

​List and activate wallets

​Issue a wallet ID token

​Inspect access credentials

​Revoke access safely

​Sign out