TypeScript SDK authentication - Polygon Developer Docs

Authentication establishes a wallet credential. Wallet selection then turns that credential into an active wallet session. Protected wallet operations remain unavailable until a wallet is active. All auth completion methods use automatic wallet selection by default. Automatic selection activates a wallet of the requested type, Ethereum by default, in this order: the first wallet the user already owns, otherwise a preallocated wallet that the SDK claims, otherwise a newly created wallet. signInWithOidcRedirect is the normal browser path for Google and Apple. Call completeOidcRedirectAuth when your application loads, then start the redirect from your sign-in UI.

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

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

await omsWallet.wallet.completeOidcRedirectAuth()

if (omsWallet.wallet.activeWallet) {
  console.log('Active wallet:', omsWallet.wallet.activeWallet.address)
}

// Run this from the user's Google sign-in action.
await omsWallet.wallet.signInWithOidcRedirect({
  provider: OmsRelayOidcProviders.google,
})

In a browser, the SDK uses the current page as the app return URL unless you pass omsRelayReturnUri. The wrapper stores transient redirect state, builds the authorization request, and navigates with window.location.assign. Callback completion validates the stored state, removes callback parameters from the browser URL by default, and returns undefined when the current URL is not the matching callback. OmsRelayOidcProviders.google and OmsRelayOidcProviders.apple are fixed OMS relay providers. Their client IDs, provider callback URLs, scopes, auth modes, and authorization parameters are SDK-owned and cannot be configured. Use a custom provider configuration when your application owns those settings.

Authenticate with email OTP

Email authentication separates code delivery from code verification so your application can render its own OTP form.

await omsWallet.wallet.startEmailAuth({
  email: 'user@example.com',
})

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

console.log(result.wallet.address)
console.log(result.credential.expiresAt)

startEmailAuth sends the code and keeps the pending attempt in memory. completeEmailAuth returns the active wallet, all wallets returned during auth, the claimableWallets that sign-in did not claim, and the credential created by the flow. credential.expiresAt is the expiry at sign-in; read the current expiry from omsWallet.wallet.session.

Authenticate with a provider ID token

Use signInWithOidcIdToken when your application already received an ID token from an identity provider SDK or another provider flow. This idToken is provider-issued input that OMS validates. It is not the OMS Wallet ID token that getIdToken later issues for your backend.

const result = await omsWallet.wallet.signInWithOidcIdToken({
  idToken: providerIdToken,
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  provider: 'google',
  providerLabel: 'Google',
})

console.log('Active wallet:', result.wallet.address)

The application must obtain providerIdToken itself and pass the exact issuer and audience used to mint it. provider and providerLabel only add display metadata to the completed session.

Control browser routing directly

Use the lower-level pair when your router or navigation layer must inspect the authorization URL before redirecting.

const { authorizationUrl } = await omsWallet.wallet.startOidcRedirectAuth({
  provider: OmsRelayOidcProviders.google,
  omsRelayReturnUri: `${window.location.origin}/auth/callback`,
})

window.location.assign(authorizationUrl)

// On /auth/callback:
const result = await omsWallet.wallet.completeOidcRedirectAuth()

For fixed relay providers, omsRelayReturnUri is your application callback. The OAuth provider itself returns to an OMS-owned relay URL derived from the publishable-key environment.

Configure a custom OIDC provider

A custom provider sends the OAuth callback directly to its providerRedirectUri.

import { type CustomOidcProviderConfig } from '@polygonlabs/oms-wallet'

const provider = {
  clientId: 'YOUR_WEB_CLIENT_ID',
  issuer: 'https://issuer.example.com',
  authorizationUrl: 'https://issuer.example.com/oauth2/authorize',
  providerRedirectUri: `${window.location.origin}/auth/callback`,
  provider: 'corporate',
  providerLabel: 'Corporate SSO',
  scopes: ['openid', 'email', 'profile'],
} satisfies CustomOidcProviderConfig

await omsWallet.wallet.signInWithOidcRedirect({ provider })

Custom providers default to authorization code with PKCE. The custom configuration owns scopes and default authorization parameters; per-call authorizeParams can add or override custom-provider parameters.

Choose a wallet type

Sessions activate an Ethereum wallet by default. Pass walletType to sign in with a Solana or Tron wallet instead:

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

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

console.log(result.wallet.type, result.wallet.address)

WalletType has Ethereum, Solana, and Tron values. For email, pass walletType to completeEmailAuth. For OIDC ID-token auth, pass it to signInWithOidcIdToken. For redirects, pass it to signInWithOidcRedirect or startOidcRedirectAuth; callback completion uses the stored value. Automatic selection activates, claims, or creates a wallet of that type, and manual selection lists only wallets of that type.

Set session lifetime

Sessions last up to 180 days by default, which is also the maximum. Pass sessionLifetimeSeconds to request a shorter lifetime. The lifetime is an upper bound: a session also ends after 10 days without use. See sessions and access. For email, pass it to startEmailAuth. For OIDC ID-token auth, pass it to signInWithOidcIdToken. For redirects, pass it when starting the flow; callback completion uses the stored value unless you override it there.

Present your own wallet selector

Pass walletSelection: 'manual' when your application must choose, claim, or create a wallet after identity verification.

await omsWallet.wallet.startEmailAuth({ email: 'user@example.com' })

const selection = await omsWallet.wallet.completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
})

const existingWallet = selection.wallets[0]
const claimableWallet = selection.claimableWallets[0]

const { wallet } = existingWallet
  ? await selection.selectWallet({ walletId: existingWallet.id })
  : claimableWallet
    ? await selection.claimAndSelectWallet({ walletId: claimableWallet.id })
    : await selection.createAndSelectWallet({ reference: 'main' })

console.log('Active wallet:', wallet.address)

Manual completion returns PendingWalletSelection. It contains a verified credential and wallet choices, but it is not an active wallet session. Complete that specific pending object with selectWallet, claimAndSelectWallet, or createAndSelectWallet. Starting another auth flow, signing out, expiring the credential, or completing a selection makes the pending object stale. The same walletSelection option is available for email, OIDC ID-token, and OIDC redirect completion.

Starting a new auth flow clears the current local wallet session before authentication continues. Do not use a sign-in action as an account-linking operation.

Claim a preallocated wallet

Your project can preallocate a receive-only wallet for a user’s email address through the OMS API, for example to fund it before the user signs in. When the user signs in and proves that email, with email OTP or an OIDC provider that reports a verified email, the wallet is claimable. Claiming makes the user its owner and lets the session sign with it. Sign-in is the only place claimable wallets are reported; listWallets includes a wallet only after it is claimed.

Automatic selection claims a claimable wallet of the requested type when the user owns none of that type. If the claim fails, sign-in fails; the SDK does not create a wallet instead.
result.claimableWallets on a completed sign-in lists the claimable wallets of every type that the sign-in did not claim. Claim one later with claimWallet.
selection.claimableWallets on a pending manual selection lists the claimable wallets of the requested type. selection.claimAndSelectWallet accepts only those IDs.

A rejected claim, for a wallet that is not allocated to the user’s verified email or was already claimed, throws OMSWalletRequestError with code OMS_REQUEST_FAILED, status 404, and upstreamError.name 'AccountNotFound'. The active wallet and the pending selection are unchanged. See sessions and access for restored state, non-browser redirect storage, wallet switching and claiming, OMS Wallet backend ID tokens, revocation, and sign-out.

​Use browser redirect sign-in

​Authenticate with email OTP

​Authenticate with a provider ID token

​Control browser routing directly

​Configure a custom OIDC provider

​Choose a wallet type

​Set session lifetime

​Present your own wallet selector

​Claim a preallocated wallet

Use browser redirect sign-in

Authenticate with email OTP

Authenticate with a provider ID token

Control browser routing directly

Configure a custom OIDC provider

Choose a wallet type

Set session lifetime

Present your own wallet selector

Claim a preallocated wallet