Swift SDK authentication - Polygon Developer Docs

Authentication establishes an OMS access credential. Wallet selection then activates a wallet and completes the session. Protected wallet operations require that completed session. Starting any new authentication flow clears the current wallet session and invalidates earlier pending authentication or wallet-selection state. Prefer native ID-token authentication when an iOS provider SDK supplies an OIDC ID token. Your app owns provider setup, consent UI, and token acquisition. Pass the provider token to OMS with the issuer and audience that minted it.

let auth = try await omsWallet.wallet.signInWithOidcIdToken(
    idToken: googleIdToken,
    issuer: "https://accounts.google.com",
    audience: "YOUR_WEB_CLIENT_ID",
    provider: "google",
    providerLabel: "Google"
)

if let wallet = auth.wallet {
    print("Active wallet:", wallet.address)
}

googleIdToken is an identity-provider input. It is not the wallet ID token returned by getIdToken(), which proves the active OMS wallet to your backend. See sessions and access. The maintained Examples/sdk-demo app in the Swift SDK repository shows Google Sign-In acquiring the provider ID token before calling signInWithOidcIdToken. 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.

Use email OTP

Email authentication is a two-step flow. The lifetime is chosen when the OTP is sent and reused when the code is completed.

try await omsWallet.wallet.startEmailAuth(
    email: "user@example.com",
    sessionLifetimeSeconds: 604_800
)

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

With the default automatic selection, auth contains the activated wallet, all wallets returned for the credential, the claimable wallets that sign-in did not claim, and WalletCredential for the new access credential.

Use an OIDC redirect

Use redirect authentication when the provider does not supply a token through a native SDK or when you need a browser authorization-code flow.

Fixed Google and Apple relay providers

OMSRelayOIDCProviders.google and .apple are fixed SDK values. Their client IDs, scopes, PKCE mode, authorization parameters, and provider callback URLs are not configurable. Supply only the URL where the OMS relay should return to your app. Start the redirect through the wallet client:

let started = try await omsWallet.wallet.startOIDCRedirectAuth(
    provider: OMSRelayOIDCProviders.google,
    omsRelayReturnURI: "yourapp://auth/callback"
)

Open started.authorizationURL, a String, as a URL (URL(string: started.authorizationURL)) with SwiftUI’s openURL environment action or the authentication browser used by your application. Register yourapp as a URL scheme, or use an associated universal link, before starting the flow.

Route the callback in SwiftUI

Pass incoming URLs directly to the SDK from SwiftUI’s onOpenURL.

ContentView()
    .onOpenURL { url in
        Task {
            do {
                let callback = try await omsWallet.wallet.handleOIDCRedirectCallback(
                    url.absoluteString
                )

                if case .completed(.walletSelected(let wallet, _, _, _)) = callback {
                    print("Active wallet:", wallet.address)
                }
            } catch {
                print("Sign-in failed:", error)
            }
        }
    }

The handler is safe to call for unrelated app links. It returns .notOIDCRedirectCallback for a URL that does not belong to OMS and .noPendingAuth when no matching attempt is stored. If the application also uses other URL-based provider SDKs, route each URL to its owner. After the OMS handler validates the callback URL and OAuth state, it consumes the stored redirect flow before completing authentication. A completed, failed, or canceled callback cannot be reused; start a new redirect flow. Values for walletSelection and sessionLifetimeSeconds passed to startOIDCRedirectAuth are stored with the pending callback. Arguments passed to handleOIDCRedirectCallback override them.

Configure a custom provider

Custom providers use their own callback directly and default to authorization code with PKCE. The app owns this configuration.

let provider = CustomOIDCProviderConfiguration(
    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: ["openid", "email", "profile"]
)

let started = try await omsWallet.wallet.startOIDCRedirectAuth(
    provider: provider
)

providerRedirectURI is both the OAuth redirect URI and the callback URL expected by the SDK.

Choose a wallet automatically or manually

Automatic selection is the default for every auth method. It activates the first wallet the user owns that matches walletType, otherwise a preallocated wallet of that type that the SDK claims, otherwise a newly created wallet. walletType defaults to .ethereum; pass .solana or .tron to sign in with a wallet of that family.

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

Set walletSelection: .manual when your app needs to present a wallet picker.

let auth = try await omsWallet.wallet.signInWithOidcIdToken(
    idToken: googleIdToken,
    issuer: "https://accounts.google.com",
    audience: "YOUR_WEB_CLIENT_ID",
    walletSelection: .manual
)

guard case .walletSelection(let pending) = auth else {
    return
}

if let wallet = pending.wallets.first {
    try await pending.selectWallet(walletId: wallet.id)
} else if let claimable = pending.claimableWallets.first {
    try await pending.claimAndSelectWallet(walletId: claimable.id)
} else {
    try await pending.createAndSelectWallet(reference: "primary")
}

PendingWalletSelection is pending, single-use, and held in memory until activation. It is not a completed or restorable wallet session, and protected wallet operations are unavailable until you select, claim, or create a wallet. A new auth flow, sign-out, expiry, or a completed selection makes the pending value stale.

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 walletType when the user owns none of that type. If the claim fails, sign-in fails; the SDK does not create a wallet instead.
auth.claimableWallets lists the claimable wallets that sign-in did not claim. Claim one later with claimWallet(walletId:).

A rejected claim, for a wallet that is not allocated to the user’s verified email or was already claimed, throws OMSWalletError with code .requestFailed, status == 404, and upstreamError?.name == "AccountNotFound".

​Sign in with OIDC token

​Use email OTP

​Use an OIDC redirect

​Fixed Google and Apple relay providers

​Route the callback in SwiftUI

​Configure a custom provider

​Choose a wallet automatically or manually

​Claim a preallocated wallet

Sign in with OIDC token