iOS SDK v13 Migration Guide
This guide upgrades Embedded Wallets iOS SDK integrations from v6 through v12 directly to v13.
If you're already on v12, focus on the v13 changes. If you're on v11 or earlier, apply the v12 changes first, then the v13 changes. For older versions, also apply the sections below that match your current version.
AI-assisted migration
For the best results, install the Web3Auth by MetaMask, Embedded Wallet SDK skill and MCP server before
you migrate.
See Build with AI for setup (npx skills add web3auth/skill and
MCP at https://mcp.web3auth.io).
Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, Antigravity, or similar):
Migrate my Embedded Wallet SDK for iOS (web3auth-swift-sdk) project to v13.
Before changing code:
1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference).
2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/ios/
3. Detect my current SDK version from Package.swift, Package.resolved, or Podfile and list which breaking changes apply.
Then migrate my codebase directly to v13:
- Update the Web3Auth dependency to 13.0.0 (Swift Package Manager or CocoaPods).
- If on v11 or earlier: replace W3AInitParams with Web3AuthOptions (web3AuthNetwork: .SAPPHIRE_MAINNET or .SAPPHIRE_DEVNET).
- If on v11 or earlier: replace login/W3ALoginParams with connectTo/LoginParams(authConnection:).
- If on v11 or earlier: replace loginConfig with authConnectionConfig ([AuthConnectionConfig]).
- If on v11 or earlier: replace getPrivkey/getEd25519PrivKey with getPrivateKey/getEd25519PrivateKey().
- If on v11 or earlier: replace launchWalletServices(chainConfig:) with showWalletUI() and configure chains in Web3AuthOptions.
- If on v11 or earlier: remove chainConfig from request(); configure chains at init instead.
- Remove any use of MFALevel.DEFAULT (removed in v13); omit mfaLevel instead.
- Keep Web3AuthOptions labeled arguments in declaration order (clientId, redirectUrl, ..., sessionTime, web3AuthNetwork, useSFAKey, walletServicesConfig, mfaSettings).
- Do not change my Client ID or Sapphire network unless I ask; that would change wallet addresses.
After migrating, list every file you changed and any manual dashboard steps I still need to do.
Use planning mode (where available) for the initial prompt. Review the plan before generating code; config mistakes can change wallet addresses in production.
Install v13
Swift Package Manager
In Xcode, go to File > Add Package Dependencies and add:
https://github.com/Web3Auth/web3auth-swift-sdk
Select Up to Next Major Version and enter 13.0.0 as the minimum version.
CocoaPods
Add to your Podfile:
pod 'Web3Auth', '~> 13.0'
Then run pod install.
Allowlist {bundleId}://auth on the
Embedded Wallets dashboard.
Breaking changes
Apply the sections below that match your current version.
v13 changes
v13 ports the SDK to Auth Service v11 and Wallet Services v6, and moves sessions to token-based sessions (access, refresh, and identity tokens). The public method signatures from v12 are unchanged, so most v12 apps only need the following updates.
MFALevel.DEFAULT removed
MFALevel now has three values: .OPTIONAL, .MANDATORY, and .NONE.
Remove any use of .DEFAULT and omit mfaLevel to get the default behavior:
// v12
LoginParams(authConnection: .GOOGLE, mfaLevel: .DEFAULT)
// v13
LoginParams(authConnection: .GOOGLE)
Default sessionTime comes from the dashboard
sessionTime is now Int?, and the default is nil.
When you don't set it, the SDK uses the session duration configured in the dashboard, whose default is 30 days, or 30 days if the dashboard returns none.
In v12, the SDK default was 30 days regardless of the dashboard.
If you changed the session duration in the dashboard, v13 apps without an explicit sessionTime
now follow that value.
Values above 30 days are still clamped to 30 days.
Initialization no longer throws for an invalid stored session
In v13, try await Web3Auth(options:) throws only if the SDK can't fetch the project
configuration.
If the SDK can't restore a stored session, it leaves web3AuthResponse as nil instead of
throwing.
Check web3AuthResponse to determine whether the user is signed in.
Wallet Services require a token-based session
showWalletUI and request now send the session's access token to Wallet Services.
Sessions created before upgrading don't have an access token, so these methods throw an error for
those users until they sign in again with v13.
Users who signed in with an idToken (SFA) aren't affected.
MFA methods and SFA users
enableMFA and manageMFA now throw Web3AuthError.enabledMfaNotAllowed for any user who
signed in with an idToken, including SFA sessions restored after the app relaunches.
In v12, these methods didn't detect SFA sign-ins.
Both methods still reuse the auth connection from the current session, as in v12.
They now also accept recordId and loginSource from the LoginParams you pass.
Session tokens and SFA users
SFA sign-in (idToken) doesn't create session tokens.
For these users, getAccessToken and getIdentityToken throw Web3AuthError.noUserFound, and
userInfo.idToken is nil.
SFA sign-in also doesn't return an Ed25519 key, so getEd25519PrivateKey throws
Web3AuthError.ed25519KeyNotFound.
Email passwordless always uses OTP
In v13.0.0, the ExtraLoginOptions initializer ignores the flow_type argument and always uses
.code (one-time code).
Passing flow_type: .link has no effect.
logout clears the app's generic password Keychain items
logout deletes every generic password item in your app's Keychain, not only the items the SDK
created.
Move data you need to keep after sign-out to another storage location.
New APIs and options
| API or option | Purpose |
|---|---|
getIdentityToken() | Returns the identity token (JWT) for server-side verification. |
getAccessToken() | Returns the session access token. |
refreshSession() | Re-authorizes the session and returns an updated Web3AuthResponse. |
getUserInfoAsync() | Returns user info and fills in idToken from the session token storage. |
WalletServicesConfig(...) public initializer | Create WalletServicesConfig directly. Adds enableKeyExport. |
WhiteLabelData tncLink, privacyPolicy | Links to your terms and privacy policy on the sign-in screens. |
LoginParams recordId, loginSource | Optional identifiers for the sign-in attempt. |
Web3AuthOptions citadelServerUrl | Override for the token-based session server URL. |
Web3AuthOptions sessionNamespace | Custom namespace for session storage. |
Web3AuthOptions useAAWithExternalWallet | Use smart accounts with external wallets in Wallet Services. |
Web3AuthOptions wsEmbedDappClientId | Client ID passed to Wallet Services. |
Web3AuthBuildEnv | Type alias for BuildEnv, for apps that also import FetchNodeDetails. |
v12 changes
v12 introduces a cleaner API surface. Key renames:
| v11 and earlier | v12 and later |
|---|---|
W3AInitParams | Web3AuthOptions |
Web3Auth(W3AInitParams(...)) | Web3Auth(options: Web3AuthOptions(...)) |
network: .sapphire_mainnet | web3AuthNetwork: .SAPPHIRE_MAINNET |
login(W3ALoginParams(loginProvider:)) | connectTo(loginParams: LoginParams(authConnection:)) |
Web3AuthProvider / .JWT | AuthConnection / .CUSTOM |
loginConfig: [String: W3ALoginConfig] | authConnectionConfig: [AuthConnectionConfig] |
W3ALoginConfig(verifier:typeOfLogin:) | AuthConnectionConfig(authConnectionId:authConnection:) |
W3AWhiteLabelData | WhiteLabelData |
useCoreKitKey | useSFAKey |
ChainConfig | Chains |
web3Auth.state (Web3AuthState) | web3Auth.web3AuthResponse (Web3AuthResponse) |
state.privKey, state.ed25519PrivKey | privateKey, ed25519PrivateKey |
userInfo.verifier, verifierId | userInfo.authConnectionId, userId |
userInfo.typeOfLogin | userInfo.authConnection |
userInfo.aggregateVerifier | userInfo.groupedAuthConnectionId |
getPrivkey() | getPrivateKey() |
getEd25519PrivKey() | getEd25519PrivateKey() (throws) |
launchWalletServices(chainConfig:) | showWalletUI() |
request(chainConfig:...) | request(method:requestParams:) |
v12 also adds single-factor authentication (SFA): pass an idToken in LoginParams to sign in
directly with your own JWT.
// v12 and later initialization
web3Auth = try await Web3Auth(
options: Web3AuthOptions(
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
redirectUrl: "com.yourapp.bundleid://auth",
chains: [
Chains(
chainId: "0x89",
displayName: "Polygon Mainnet",
rpcTarget: "https://rpc.ankr.com/polygon"
)
],
web3AuthNetwork: .SAPPHIRE_MAINNET
)
)
// v12 and later sign-in
let result = try await web3Auth.connectTo(
loginParams: LoginParams(authConnection: .GOOGLE)
)
// v12 and later wallet services
try await web3Auth.showWalletUI()
The full Web3AuthOptions initializer requires labeled arguments in declaration order.
Pass clientId and redirectUrl first, and place web3AuthNetwork after sessionTime and before
useSFAKey.
See Web3AuthOptions.
Network and init params (from v7)
Use Sapphire networks:
web3Auth = Web3Auth(W3AInitParams(
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
network: .sapphire_mainnet, // or .sapphire_devnet
redirectUrl: "com.yourapp.bundleid://auth",
))
W3AInitParams adds buildEnv, mfaSettings, and sessionTime.
Configure MFA through mfaSettings instead of adapter-level options.
See MFA.
Whitelabel configuration (from v7)
W3AWhiteLabelData field names changed:
| v6 and earlier | v7 and later |
|---|---|
name | appName |
dark | mode (.light, .dark, or .auto) |
New optional fields include appUrl and useLogoLoader.
Prefer dashboard customization for new projects.
If your app uses web3.swift, note that v7 updated the dependency to v1.6.0 with API changes in
Ethereum client calls.
Mandatory redirect URL (from v8.4)
redirectUrl is required in W3AInitParams:
redirectUrl: "com.yourapp.bundleid://auth"
launchWalletServices signature (from v8.1 and v8.2)
From v8.1, move chainConfig out of W3AInitParams and into launchWalletServices.
From v8.2, remove loginParams:
var chainConfig = ChainConfig(
chainNamespace: ChainNamespace.eip155,
chainId: "0x1",
rpcTarget: "https://mainnet.infura.io/v3/<YOUR_KEY>",
ticker: "ETH",
)
try await web3Auth?.launchWalletServices(chainConfig: chainConfig)
request signature (from v8.3)
Remove loginParams.
Pass chainConfig, method name, and request parameters:
var params = [Any]()
params.append("Hello, World!")
params.append("0x764dd67c0420b43a39ab337463d8995622f226a2")
var chainConfig = ChainConfig(
chainNamespace: ChainNamespace.eip155,
chainId: "0x1",
rpcTarget: "https://mainnet.infura.io/v3/<YOUR_KEY>",
ticker: "ETH",
)
let response = try await web3Auth?.request(
chainConfig: chainConfig,
method: "personal_sign",
requestParams: params,
)
v10 changes
getSignResponse() is removed.
The request() method returns SignResponse directly:
let response = try await web3Auth?.request(
chainConfig: chainConfig,
method: "personal_sign",
requestParams: params,
)
if response!.success {
print(response!.result!)
} else {
print(response!.error!)
}
v10 also adds support for Web3Auth Auth Service v9 and Wallet Services v3 (including swap in the prebuilt wallet UI).
New APIs (non-breaking)
These APIs were added in intermediate versions. If you're upgrading from an older SDK, adopt the v13 signatures shown above.
| API | Added in | Purpose |
|---|---|---|
enableMFA() | v8 | Initiate MFA setup for logged-in users |
launchWalletServices() | v8 | Open the built-in wallet UI |
request() | v8 | Sign transactions with confirmation screens |
| SMS Passwordless sign-in | v8.3 | Web3AuthProvider.SMS_PASSWORDLESS with loginHint |
| Farcaster sign-in | v8.3 | .Farcaster sign-in provider |
SFA sign-in (idToken) | v12 | LoginParams(idToken:) in connectTo |
| Session token methods | v13 | getIdentityToken, getAccessToken, refreshSession |
See Wallet Services and MFA for usage details.
Summary table
| Area | Before v7 | v7-v11 | v12 | v13 |
|---|---|---|---|---|
| Network | .mainnet, .cyan, etc. | Sapphire supported | .SAPPHIRE_MAINNET | .SAPPHIRE_MAINNET |
| Init params | W3AInitParams | W3AInitParams | Web3AuthOptions | Web3AuthOptions |
| Sign-in | N/A | login(W3ALoginParams) | connectTo(LoginParams) | connectTo(LoginParams) |
redirectUrl | Optional | Mandatory (v8.4+) | Mandatory | Mandatory |
Whitelabel name | name | appName | appName | appName |
| Wallet UI | N/A | launchWalletServices | showWalletUI() | showWalletUI() |
request | N/A | chainConfig parameter | Chains in Web3AuthOptions | Chains in Web3AuthOptions |
| Sign result | N/A | getSignResponse() (v9) | Return value of request() | Return value of request() |
MFALevel | Includes DEFAULT | Includes DEFAULT | Includes DEFAULT | OPTIONAL, MANDATORY, NONE |
| Default session | 1 day, set in W3ALoginParams (max 7 days) | 1 day (max 7 days); sessionTime moves to W3AInitParams in v7.3; max 30 days from v11.0.3; default 30 days from v11.1 | 30 days | 30 days, from the dashboard session duration |
| Sessions | Session ID | Session ID | Session ID | Access, refresh, and identity tokens |
Next steps
- iOS SDK get started
- Build with AI for ongoing integration help
- Release notes