TypeScript 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 exposes one active walletAddress at a time.

Read and restore session state

Create OMSWallet with the same publishable key and storage configuration on each application load. The constructor synchronously restores unexpired session metadata. Protected wallet operations also verify the corresponding signer credential.

import { OMSWallet } from '@polygonlabs/oms-wallet'

const omsWallet = new OMSWallet({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})

const { walletAddress, expiresAt, auth } = omsWallet.wallet.session

if (walletAddress) {
  console.log('Restored wallet:', walletAddress)
  console.log('Credential expires:', expiresAt)
  console.log('Authentication:', auth)
}

wallet.session is a read-only snapshot:

walletAddress and expiresAt are defined only for an active session.
Email auth metadata is { type: 'email', email }.
OIDC metadata is { type: 'oidc', flow, issuer, provider, providerLabel, email }. Optional provider fields can be undefined.

The stored record is scoped to the publishable-key project and API environment. Restoration also requires the same local signer credential ID and signing algorithm.

Understand storage defaults

Browser defaults use separate storage for completed sessions and pending redirects:

Completed session metadata uses localStorage.
The default non-extractable WebCrypto P-256 signer stores its credential in IndexedDB.
Temporary OIDC verifier and state data use sessionStorage.

Outside a browser, completed session metadata defaults to in-memory storage, so it does not survive a process restart. Redirect storage has no non-browser default. Pass redirectAuthStorage before calling any redirect auth method, and make sure it remains available to the callback process. For a non-browser runtime, provide application-owned implementations of the public StorageManager and CredentialSigner interfaces through the storage, redirectAuthStorage, and credentialSigner constructor options. See the package API reference for their exact contracts. For the redirect convenience wrapper outside a browser, pass currentUrl and assignUrl. On completion, pass callbackUrl; either keep cleanUrl: false or provide replaceUrl when URL cleanup is required. An in-memory redirect store is suitable only when both stages run in the same process. See authentication for the lower-level browser flow.

Respond to expiry

The SDK makes an expired session inactive before protected operations. Subscribe while your application needs to update its routing or UI.

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

// Call during application or component cleanup.
unsubscribe()

An expiry event includes the expired session snapshot even though wallet.walletAddress is now undefined. A newly constructed client can replay a stored expiry event to a listener. Starting authentication, completing a new session, or signing out clears that replay state.

List and activate wallets

List every wallet available to the authenticated credential:

const wallets = await omsWallet.wallet.listWallets()

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

listWallets works with an active session and while manual auth selection is pending. After normal automatic auth, switch the active wallet with its server-side ID:

const wallet = wallets[0]

if (wallet) {
  const active = await omsWallet.wallet.useWallet({ walletId: wallet.id })
  console.log('Now active:', active.walletAddress)
}

useWallet requires an active session and preserves its credential expiry and auth metadata. If auth returned PendingWalletSelection, call selection.selectWallet instead.

Create and activate another wallet

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

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

createWallet creates an Ethereum wallet by default and immediately makes it active. A pending manual selection must use selection.createAndSelectWallet instead.

Issue an ID token for your backend

getIdToken asks OMS Wallet to issue an ID token that proves the active wallet session to your backend.

const idToken = await omsWallet.wallet.getIdToken({
  ttlSeconds: 300,
  customClaims: { purpose: 'checkout' },
})

This token is OMS Wallet output. It is distinct from the provider-issued ID token passed into signInWithOidcIdToken during authentication. Treat client-supplied custom claims as untrusted context unless your backend independently controls or validates them. See backend wallet verification.

Review and revoke access

listAccess follows all service pages and returns credentials with access to the active wallet. Use listAccessPages when you want page-at-a-time rendering.

const grants = await omsWallet.wallet.listAccess()

for (const grant of grants) {
  console.log(grant.credentialId, grant.expiresAt, grant.isCaller)
}

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

Revoke only a credential that is not the caller for the current session:

const revocableGrant = grants.find((grant) => !grant.isCaller)

if (revocableGrant) {
  await omsWallet.wallet.revokeAccess({
    targetCredentialId: revocableGrant.credentialId,
  })
}

Do not offer revokeAccess for a grant whose isCaller field is true. It represents the credential making the current request. Revocation is permanent for the target grant.

Sign out locally

await omsWallet.wallet.signOut()

signOut clears the local session record, pending auth state, active wallet, and local credential signer where supported. It does not call the OMS service and does not revoke server-side access grants. Use revokeAccess separately for other grants before signing out when your account-management flow requires revocation.

​Read and restore session state

​Understand storage defaults

​Respond to expiry

​List and activate wallets

​Create and activate another wallet

​Issue an ID token for your backend

​Review and revoke access

​Sign out locally

Read and restore session state

Understand storage defaults

Respond to expiry

List and activate wallets

Create and activate another wallet

Issue an ID token for your backend

Review and revoke access

Sign out locally