Swift sessions and access - Polygon Developer Docs

An active session combines a selected wallet with an unexpired OMS credential. The SDK persists completed session metadata and restores it when you create OMSWallet again.

Read restored session state

let omsWallet = try OMSWallet(publishableKey: "YOUR_PUBLISHABLE_KEY")

if let activeWallet = omsWallet.wallet.activeWallet,
   let session = omsWallet.wallet.session {
    print("Restored wallet:", activeWallet.type, activeWallet.address)
    print("Expires:", session.expiresAt)
    print("Identity:", session.auth.email ?? "none")
}

activeWallet is the selected Wallet, with its id, type, address, reference, and keyOrigin. Check type before passing the address to code for one network family. session is an OMSWalletSession with the current expiry in expiresAt and authentication metadata in auth. Both are nil when no wallet session is active, and session is non-nil exactly when activeWallet is. For OIDC, the metadata identifies .idToken or .redirect, the issuer, optional provider details, and an email when OMS returns one. The session’s signing key is generated in the Secure Enclave on an iOS device (in the Keychain in the Simulator and on macOS), cannot be exported, and is never part of OMSWalletSession.

A manual PendingWalletSelection is not completed session metadata. It remains in memory only until your app activates a wallet.

One wallet per project

Creating OMSWallet again for the same project and environment returns the same wallet, so every part of your app sees the same session. A rotated publishable key for the same project keeps the session.

Keep your UI in sync

A session stays active while it is used. It ends after about 10 days without use, or at the lifetime requested at sign-in (180 days by default). session.expiresAt is the current expiry as an ISO-8601 timestamp, and the SDK keeps it up to date. When the session ends, protected operations throw OMSWalletError with code .sessionExpired. If the wallet API cannot be reached, the session is kept and operations throw the network error. addSessionChangeObserver calls your observer on MainActor after every change of activeWallet or session. Add the observer first, then read the current state, so no change is missed. Keep the returned observation: delivery stops when it is cancelled or released.

let observation = omsWallet.wallet.addSessionChangeObserver { change in
    render(change.activeWallet, change.session)

    if case .expired(let expired) = change {
        showSignIn(expired.session.auth)
    }
}
render(omsWallet.wallet.activeWallet, omsWallet.wallet.session)

Change	Meaning
`.signedIn`	A sign-in made a wallet active
`.restored`	A saved session became active after launch, for example once the device was unlocked
`.walletChanged`	Another wallet of the same sign-in became active
`.expiryUpdated`	`session.expiresAt` moved; safe to ignore unless you show it
`.signedOut`	The session ended without expiring, for example `signOut()` or a new sign-in starting while signed in
`.expired`	The session expired; it carries the wallet and authentication for signing in again

After a relaunch, a new observer first receives the last .expired change until the user signs in again or signs out.

List, switch, and create wallets

These operations require the authenticated credential. listWallets() follows all server cursors and returns the complete list.

let wallets = try await omsWallet.wallet.listWallets()

if let secondary = wallets.dropFirst().first {
    let selected = try await omsWallet.wallet.useWallet(
        walletId: secondary.id
    )
    print("Selected:", selected.wallet.address)
}

Create and activate another wallet for the same credential when your product requires one.

let created = try await omsWallet.wallet.createWallet(
    reference: "trading"
)

print("Created:", created.wallet.address)

Both useWallet and createWallet replace the active wallet while preserving the current session expiry and authentication metadata. Pass walletType: .solana or walletType: .tron to create a Solana or Tron wallet:

let solana = try await omsWallet.wallet.createWallet(
    walletType: .solana,
    reference: "solana-primary"
)

let tron = try await omsWallet.wallet.createWallet(
    walletType: .tron,
    reference: "tron-primary"
)

Claim a preallocated wallet

A completed sign-in result lists, in claimableWallets, the wallets your project preallocated for the user’s email that sign-in did not claim. See authentication for how wallets become claimable. Claim one with claimWallet(walletId:):

let auth = try await omsWallet.wallet.completeEmailAuth(code: "123456")

if let claimable = auth.claimableWallets.first {
    let claimed = try await omsWallet.wallet.claimWallet(walletId: claimable.id)
    print("Claimed:", claimed.wallet.type, claimed.wallet.address)
}

claimWallet makes the claimed wallet active, like useWallet. During a pending manual selection, use pending.claimAndSelectWallet(walletId:) instead.

Import and activate a wallet

let imported = try await omsWallet.wallet.importWallet(
    privateKey: .ethereum("0x..."), // Supply the key from your secure migration flow.
    reference: "imported-wallet"
)

print(imported.wallet.keyOrigin == .imported)

Ethereum and Tron imports take a private key as bytes or a hex string, through .ethereum or .ethereumBytes and .tron or .tronBytes. Solana imports take a 32-byte seed or 64-byte keypair, as bytes or base58. The SDK never stores the plaintext key. keyOrigin tells you whether a wallet was created by OMS (.enclave) or imported (.imported). Attestation failures throw OMSWalletError with code .attestationVerificationFailed. Importing a key whose address is already managed throws .walletAddressAlreadyImported and leaves the active wallet unchanged; select the existing wallet or use a different key.

Development uses Nitro debug-mode attestation. Use only disposable test keys in Development. Staging and Production verify against SDK-pinned enclave measurements.

Understand access objects

Keep these three objects distinct:

Object	Purpose
Wallet session	Local active-wallet state used by protected SDK operations.
Wallet ID token	Short-lived token returned by OMS for your backend to verify the active wallet.
Access grant	A direct `WalletCredential` or remote smart session that can make signed requests for the wallet until it expires or is revoked.

The OIDC provider ID token used during authentication is a fourth object: it is app-owned identity proof consumed as auth input, not an OMS wallet token.

Request a wallet ID token

Call getIdToken() only after a wallet is active. Send the returned string to a backend that verifies it using the OMS issuer and JWKS flow described in backend wallet verification.

let walletIdToken = try await omsWallet.wallet.getIdToken(
    ttlSeconds: 3_600,
    customClaims: [
        "role": .string("member")
    ]
)

Custom claims originate in the client. Your backend should not treat them as trusted authorization state unless it controls how they are assigned.

List and revoke access grants

Use listAccess() to load all access-grant pages for account-management UI.

let grants = try await omsWallet.wallet.listAccess()

for grant in grants {
    switch grant {
    case .direct(let credential):
        print(credential.credentialId, credential.isCaller)
    case .remote(let remote):
        print(remote.credential.credentialId, remote.sessionId)
        print(remote.metadata, remote.grants)
    }
}

Use the async sequence when your UI should process one server page at a time.

for try await page in omsWallet.wallet.listAccessPages(pageSize: 25) {
    for grant in page.grants {
        print(grant.credential.credentialId, grant.credential.isCaller)
    }
}

You can also request one page with listAccessPage(pageSize:cursor:type:). Revoke only a grant whose credential has isCaller == false:

if let grant = grants.first(where: { !$0.credential.isCaller }) {
    switch grant {
    case .direct(let credential):
        try await omsWallet.wallet.revokeAccess(
            credentialId: credential.credentialId
        )
    case .remote(let remote):
        try await omsWallet.wallet.revokeAccess(
            credentialId: remote.credential.credentialId,
            sessionId: remote.sessionId
        )
    }
}

For a remote grant, sessionId is required and revokes exactly that session. Revocation cannot be undone. Revoking the caller invalidates the credential making the current request and prevents subsequent protected operations from that session. Keep caller revocation out of the normal access-management UI.

Authorize remote access

Remote access grants are bounded EVM smart sessions. Inspect the remote credential and show its returned metadata to the wallet owner before requesting approval: This example uses Polygon Amoy. Grant limits are raw EVM base-unit amounts. A native-transfer limit is cumulative, so 1000000000000000 wei authorizes up to 0.001 POL across the session.

import Foundation

let credentialId = "REMOTE_CREDENTIAL_ID"
let metadata = try await omsWallet.wallet.inspectRemoteCredential(
    credentialId: credentialId
)

// Render the returned metadata in your consent UI and continue only after approval.
print(metadata.appName, metadata.appUrl)

let session = try await omsWallet.wallet.authorizeRemoteAccess(
    credentialId: credentialId,
    network: .amoy,
    grants: [
        .nativeTransfer(
            to: "0x1111111111111111111111111111111111111111",
            // Cumulative 0.001 POL limit in wei.
            limit: "1000000000000000"
        )
    ],
    expiresAt: ISO8601DateFormatter().string(
        from: Date().addingTimeInterval(3_600)
    )
)

let details = try await omsWallet.wallet.getRemoteAccessSession(
    sessionId: session.sessionId
)
let usage = try await omsWallet.wallet.getRemoteAccessSessionUsage(
    sessionId: session.sessionId,
    network: .amoy
)

WaaS caps the requested session expiry at the remote credential’s expiry. A wallet can have up to 100 active remote sessions by default. At the limit, authorizeRemoteAccess fails with .requestFailed (upstreamError?.code "7208"); revoke a session the wallet no longer needs, then try again. Backend credential registration and remote execution are outside the Swift SDK; implement them with the TypeScript SDK’s backend smart sessions guide.

Sign out

try omsWallet.wallet.signOut()

Signing out clears the completed session, Keychain credential, pending redirect state, and pending wallet selection for this SDK scope. It does not revoke other access credentials on the wallet.