Kotlin SDK sessions and access - Polygon Developer Docs

A completed session combines an authenticated credential with one selected wallet. The Android-backed OMSWallet constructor restores that session automatically when its metadata is valid, unexpired, and still matches the Android Keystore credential. Protected methods on omsWallet.wallet require this active session. Read-only calls on omsWallet.indexer do not.

Read the completed session

val session = omsWallet.wallet.session

println("Wallet: ${session.walletAddress}")
println("Expires at: ${session.expiresAt}")
println("Authenticated email: ${session.auth?.email}")

walletAddress is non-null only after wallet activation. expiresAt is the ISO-8601 value returned by OMS. auth is OMSWalletEmailSessionAuth or OMSWalletOidcSessionAuth; OIDC metadata also records the Redirect or IdToken flow and issuer. Pending email OTP and manual wallet-selection attempts are not persisted. Pending redirect state is stored separately and must be completed through handleOidcRedirectCallback. Do not use session.walletAddress == null to infer which pending flow, if any, is active.

Handle expiration

An expired session becomes inactive before protected wallet work proceeds. The operation throws OMSWalletSessionException with code = OMSWalletErrorCode.SessionExpired. Subscribe when the UI should react as the session expires:

val unsubscribe = omsWallet.wallet.onSessionExpired { event ->
    println("Reauthenticate ${event.session.auth?.email.orEmpty()}")
}

// Call when the lifecycle owner no longer needs the callback.
unsubscribe()

Listeners run on the Android main thread. A new listener receives the latest expiration event until a new auth flow, a new completed session, or signOut() clears it. The event contains the expired snapshot, not a still-active session.

List, switch, and create wallets

List every wallet available to the authenticated credential:

val wallets = omsWallet.wallet.listWallets()

wallets.forEach { wallet ->
    println("${wallet.id}: ${wallet.address}")
}

Activate a different existing wallet by its OMS wallet ID:

val selected = omsWallet.wallet.useWallet(walletId = wallets.last().id)
println("Active wallet: ${selected.walletAddress}")

Or create and activate a wallet:

val created = omsWallet.wallet.createWallet(reference = "savings")
println("Created wallet: ${created.wallet.address}")

Both activation methods update the persisted completed session. reference is optional app-defined wallet metadata.

Keep the three credential concepts separate

The SDK uses three related values for different trust boundaries:

Value	Purpose
Completed wallet session	Local SDK state containing the selected wallet, expiry, and auth metadata
OMS Wallet ID token	A token from `getIdToken()` that your app sends to its backend as proof for the active wallet
Request-signing access credential	An SDK-managed P-256 credential that authorizes wallet API requests and appears in access-management results

The provider ID token passed to signInWithOidcIdToken is a fourth value used only to authenticate the user’s external identity. It is not the token returned by getIdToken().

Issue an ID token for your backend

val idToken = omsWallet.wallet.getIdToken(
    ttlSeconds = 300u,
)

Send this token to your backend and verify it there as described in Backend wallet verification. customClaims accepts Map<String, JsonElement> when you need app-provided context. Treat app-provided claims as untrusted unless your backend controls their values.

Inspect request-signing access

listAccess follows all cursors and returns the credentials that can access the selected wallet:

val credentials = omsWallet.wallet.listAccess(pageSize = 25u)

credentials.forEach { credential ->
    println("${credential.credentialId} caller=${credential.isCaller}")
}

Each CredentialInfo includes credentialId, ISO-8601 expiresAt, and isCaller. For page-at-a-time UI, use listAccessPage(pageSize, cursor). For a stream of pages, collect listAccessPages(pageSize). Revoke only a credential whose isCaller value is false:

credentials.firstOrNull { !it.isCaller }?.let { credential ->
    omsWallet.wallet.revokeAccess(
        targetCredentialId = credential.credentialId,
    )
}

Revocation changes that credential’s server-side wallet access. Revoking the caller invalidates the credential making the current request and prevents subsequent protected operations from that session. It does not switch the selected wallet.

Sign out

omsWallet.wallet.signOut()

signOut() synchronously clears in-memory state and attempts to remove completed-session metadata, pending redirect state, and the local request-signing credential. If persistent cleanup fails, it throws OMSWalletStorageException after the in-memory session has already been cleared.

​Read the completed session

​Handle expiration

​List, switch, and create wallets

​Keep the three credential concepts separate

​Issue an ID token for your backend

​Inspect request-signing access

​Sign out