Kotlin SDK authentication - Polygon Developer Docs

Authentication establishes an OMS credential. Wallet selection then activates a wallet for that credential and completes the session. Protected wallet operations require both steps. Starting any authentication flow replaces the current wallet session and pending authentication state. Prefer OIDC ID-token authentication when a native provider SDK supplies an ID token. Your app owns provider sign-in and token acquisition. The OMS Wallet SDK receives the resulting token but does not invoke Android Credential Manager or another provider SDK for you. Pass the provider result directly to OMS Wallet:

import technology.polygon.omswallet.wallet.CompleteAuthResult

val result = omsWallet.wallet.signInWithOidcIdToken(
    idToken = googleIdToken,
    issuer = "https://accounts.google.com",
    audience = "YOUR_WEB_CLIENT_ID",
)
check(result is CompleteAuthResult.WalletSelected)

println("Wallet address: ${result.wallet.address}")

idToken must be a compact JWT whose payload contains a numeric exp claim. Pass the provider ID token, not an OAuth access token or authorization code. issuer and audience must match the provider configuration used to obtain it. For a custom issuer, you can also set provider and providerLabel; these values become session metadata. The maintained Kotlin SDK demo shows Google Sign-In obtaining googleIdToken with Android Credential Manager. Generate provider nonces with a cryptographically secure random source and handle provider errors in the application integration.

Authenticate with email OTP

Email authentication has an in-memory pending step. It is not restored after process death.

import technology.polygon.omswallet.wallet.CompleteAuthResult

omsWallet.wallet.startEmailAuth(
    email = "user@example.com",
)

// Complete this after the user enters the emailed code.
val result = omsWallet.wallet.completeEmailAuth(
    code = "123456",
)
check(result is CompleteAuthResult.WalletSelected)

startEmailAuth stores the requested session lifetime with that pending attempt. A new auth flow or signOut() clears it.

Authenticate through an OIDC redirect

Use redirect authentication when you cannot obtain a provider ID token directly. Unlike email and manual selection state, the Android-backed client persists pending redirect state so the browser round trip can survive activity or process recreation. For the fixed Google or Apple OMS relay configuration, start the flow with an app callback URI:

import technology.polygon.omswallet.wallet.OmsRelayOidcProviders

val started = omsWallet.wallet.startOidcRedirectAuth(
    provider = OmsRelayOidcProviders.google,
    omsRelayReturnUri = "yourapp://auth/callback",
)

println("Open in Custom Tabs: ${started.authorizationUrl}")

Register the callback URI for your Android app. The Google and Apple relay values have fixed SDK-owned client IDs, scopes, authorization parameters, and PKCE behavior. For a provider configuration owned by your app, use CustomOidcProviderConfig. Its providerRedirectUri is both the OAuth redirect URI and expected callback URI.

import technology.polygon.omswallet.wallet.CustomOidcProviderConfig

val started = omsWallet.wallet.startOidcRedirectAuth(
    provider = CustomOidcProviderConfig(
        issuer = "https://issuer.example.com",
        clientId = "YOUR_OIDC_CLIENT_ID",
        authorizationUrl = "https://issuer.example.com/oauth2/authorize",
        providerRedirectUri = "yourapp://auth/callback",
        provider = "corporate",
        providerLabel = "Corporate SSO",
        scopes = listOf("openid", "email", "profile"),
    ),
)

Handle the redirect callback

Pass incoming callback URLs from both onCreate and onNewIntent to the handler:

import technology.polygon.omswallet.wallet.CompleteAuthResult
import technology.polygon.omswallet.wallet.OidcRedirectAuthResult

when (
    val callback = omsWallet.wallet.handleOidcRedirectCallback(
        callbackUrl = intent.data?.toString(),
    )
) {
    is OidcRedirectAuthResult.Completed -> {
        val auth = callback.result
        check(auth is CompleteAuthResult.WalletSelected)
        println(auth.wallet.address)
    }
    OidcRedirectAuthResult.NotOidcRedirectCallback -> Unit
    OidcRedirectAuthResult.NoPendingAuth -> println("Start a new sign-in")
}

The handler checks the callback URI and encoded state before consuming pending state. A null, unrelated, or state-mismatched URL returns NotOidcRedirectCallback and leaves the pending redirect available. An OIDC-shaped callback with no stored attempt returns NoPendingAuth. A matching callback is consumed once: success returns Completed, while provider or completion failures throw an OMSWalletException and clear that attempt. Pass walletSelection or sessionLifetimeSeconds when starting the redirect to persist those choices for completion. A non-null callback argument overrides its stored value.

Set the session lifetime

Sessions last up to 180 days by default, which is also the maximum. Pass sessionLifetimeSeconds to request a shorter lifetime; an invalid value throws OMSWalletValidationException. The lifetime is an upper bound: a session also ends after 10 days without use. See Keep your UI in sync. For email, set sessionLifetimeSeconds on startEmailAuth. For ID-token auth, set it on signInWithOidcIdToken. For redirects, set it when starting the flow or override it when handling the callback.

Select a wallet manually

OIDC ID-token, email, and redirect authentication use WalletSelectionBehavior.Automatic by default. Automatic mode selects the first wallet the user owns that matches the requested type, otherwise claims and selects a preallocated wallet of that type, otherwise creates a wallet. Choose the wallet type with the walletType parameter of completeEmailAuth, signInWithOidcIdToken, or startOidcRedirectAuth. It defaults to WalletType.Ethereum. For example, pass walletType = WalletType.Solana or walletType = WalletType.Tron to completeEmailAuth to select, claim, or create a Solana or Tron wallet. Use manual mode only when your app presents the wallet choices:

import technology.polygon.omswallet.wallet.CompleteAuthResult
import technology.polygon.omswallet.wallet.WalletSelectionBehavior

val result = omsWallet.wallet.completeEmailAuth(
    code = "123456",
    walletSelection = WalletSelectionBehavior.Manual,
)
check(result is CompleteAuthResult.WalletSelection)

val pending = result.pendingSelection
val existing = pending.wallets.firstOrNull()
val claimable = pending.claimableWallets.firstOrNull()
val selected = when {
    existing != null -> pending.selectWallet(existing.id)
    claimable != null -> pending.claimAndSelectWallet(claimable.id)
    else -> pending.createAndSelectWallet(reference = "main")
}

println("Selected wallet: ${selected.wallet.address}")

CompleteAuthResult.WalletSelection means identity authentication succeeded, but no wallet is active. Complete that same pending attempt with selectWallet, claimAndSelectWallet, or createAndSelectWallet. The pending value becomes stale after selection, a newer auth flow, sign-out, or credential expiry. Redirect authentication returns the same result when it starts with manual selection.

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 same way a failed wallet creation does; the SDK does not create a wallet instead.
CompleteAuthResult.WalletSelected.claimableWallets lists the claimable wallets of every type that sign-in did not claim. Claim one later with claimWallet.
pendingSelection.claimableWallets lists the claimable wallets of the requested type. claimAndSelectWallet accepts only those IDs and completes the selection.

A rejected claim, for a wallet that is not allocated to the user’s verified email or was already claimed, throws OMSWalletRequestException with code = OMSWalletErrorCode.RequestFailed, status = 404, and upstreamError.name == "AccountNotFound". The active wallet is unchanged. Continue with Sessions and access to restore completed sessions, switch or claim wallets, issue backend ID tokens, and manage request-signing credentials.

​Sign in with OIDC ID token

​Authenticate with email OTP

​Authenticate through an OIDC redirect

​Handle the redirect callback

​Set the session lifetime

​Select a wallet manually

​Claim a preallocated wallet

Sign in with OIDC ID token