From 0ab403b43829d38531854a3f3b0f26344d42c0b0 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:57:27 +0530 Subject: [PATCH 1/3] Fix Embedded Wallets client secret rotation and React Native useCoreKitKey guidance Co-authored-by: Cursor --- .../dashboard/project-settings.mdx | 4 +++- .../migration-guides/react-native.mdx | 18 ++++++++++++------ 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/embedded-wallets/dashboard/project-settings.mdx b/embedded-wallets/dashboard/project-settings.mdx index 138d20a0be4..b02bff76227 100644 --- a/embedded-wallets/dashboard/project-settings.mdx +++ b/embedded-wallets/dashboard/project-settings.mdx @@ -53,7 +53,9 @@ The Client ID is safe to expose in client-side code and cannot be changed after ### Client secret -A confidential key for server-side API requests. Never expose it in frontend code, mobile apps, or any publicly accessible environment. Store it in environment variables or a secrets manager. You can regenerate it from the dashboard if it is compromised. +A confidential key for server-side API requests. Never expose it in frontend code, mobile apps, or any publicly accessible environment. Store it in environment variables or a secrets manager. Only use it when your backend needs it to create wallets programmatically. + +The client secret cannot be regenerated from the dashboard. Rotating it would change every wallet on the project, which means starting a new project. :::danger diff --git a/embedded-wallets/migration-guides/react-native.mdx b/embedded-wallets/migration-guides/react-native.mdx index 6911f869ed2..85d01ee656b 100644 --- a/embedded-wallets/migration-guides/react-native.mdx +++ b/embedded-wallets/migration-guides/react-native.mdx @@ -34,7 +34,8 @@ ROLE You are a code-migration agent. Your job is to upgrade the open repository to @web3auth/react-native-sdk v9 (MetaMask Embedded Wallets). Stay inside the repo. Do not run package-manager installs, git commands, or shell side effects unless the user explicitly approves them; only propose them. CONTEXT -v9 is a hooks-first API. The legacy imperative pattern (new Web3Auth(...), .init(), .login(), privateKeyProvider, loginConfig, useCoreKitKey, useSFAKey, OPENLOGIN_NETWORK, LOGIN_PROVIDER, manual globals.js, manual Metro polyfills, @web3auth/ethereum-provider, @web3auth/solana-provider, SolanaWallet) is removed. +v9 is a hooks-first API. The legacy imperative pattern (new Web3Auth(...), .init(), .login(), privateKeyProvider, loginConfig, useSFAKey, OPENLOGIN_NETWORK, LOGIN_PROVIDER, manual globals.js, manual Metro polyfills, @web3auth/ethereum-provider, @web3auth/solana-provider, SolanaWallet) is removed. +useCoreKitKey is still supported. If the existing app sets useCoreKitKey: true, keep it in v9, or existing users get a different wallet. KNOWLEDGE SOURCES (do not guess Web3Auth APIs from memory) - Use the "web3auth" skill and Web3Auth MCP server to learn about MetaMask Embedded Wallets and confirm package names, hooks, and configuration. If the skill is missing, ask the user to run: npx skills add web3auth/skill @@ -86,7 +87,8 @@ E. web3authConfig.ts (create if missing) - export default a value typed as Web3AuthContextConfig from '@web3auth/react-native-sdk'. - Required: clientId, redirectUrl ('scheme://auth'), network (WEB3AUTH_NETWORK.*). - chains / defaultChainId are OPTIONAL when chains are configured on the Embedded Wallets dashboard; add them locally for custom RPCs, Solana, or multi-chain (see rn-bare-solana-example). - - Do NOT include privateKeyProvider, loginConfig, useCoreKitKey, or useSFAKey. + - Do NOT include privateKeyProvider, loginConfig, or useSFAKey. + - If the existing code sets useCoreKitKey: true, keep it in web3AuthOptions. Removing it gives existing users a different wallet. - Preserve clientId, RPCs, redirect scheme, and whitelabel values from existing code. F. App root (hooks only) @@ -164,7 +166,7 @@ Inspect the codebase and classify the starting point: | `globals.js` + `crypto-browserify` in Metro | v3-v6 legacy polyfills | | `react-native-quick-crypto` in Metro `resolveRequest` | v6 (remove manual wiring; do not add for v9) | | `whiteLabel.name` or `whiteLabel.dark` | v4 or earlier whitelabel | -| `loginConfig`, `LOGIN_PROVIDER.JWT`, `useCoreKitKey` | v8 custom auth (maps to v9 `connectTo`) | +| `loginConfig`, `LOGIN_PROVIDER.JWT`, `useCoreKitKey` | v8 custom auth (maps to v9 `connectTo`; keep `useCoreKitKey: true`) | You can jump from any row directly to v9; you do not need intermediate upgrades. @@ -187,7 +189,8 @@ You can jump from any row directly to v9; you do not need intermediate upgrades. | `loginConfig` + `verifier` | Dashboard connection + `authConnectionId` in `connectTo` | | `verifierSubIdentifier` | `groupedAuthConnectionId` in `connectTo` | | `LOGIN_PROVIDER.JWT` + `id_token` in `extraLoginOptions` | `AUTH_CONNECTION.CUSTOM` + `authConnectionId` + top-level `idToken` | -| `useCoreKitKey` / `useSFAKey` | **Removed**, delete | +| `useCoreKitKey: true` | Keep it in `web3AuthOptions`; removing it changes existing users' wallets | +| `useSFAKey` | **Removed**, delete | | `launchWalletServices(chainConfig)` | `showWalletUI()` via `useWalletUI()` | | `request(chainConfig, method, params)` | `request(method, params)` via `useSignatureRequest()` | | `SolanaWallet` / `@web3auth/solana-provider` | `web3Auth.signer` as `TransactionSigner` | @@ -483,7 +486,9 @@ export default web3AuthConfig **Solana**, set `chainNamespace: CHAIN_NAMESPACES.SOLANA` in `chains` when not using dashboard-only config. See [rn-bare-solana-example](https://github.com/Web3Auth/web3auth-react-native-examples/tree/main/rn-bare-solana-example). Do not use `SolanaPrivateKeyProvider` or `@web3auth/solana-provider`. -**Removed from v8 options** (delete if present): `privateKeyProvider`, `loginConfig`, `useCoreKitKey`, `useSFAKey`. +**Removed from v8 options** (delete if present): `privateKeyProvider`, `loginConfig`, `useSFAKey`. + +**Keep `useCoreKitKey: true`** if your v8 app set it. v9 still supports it, and removing it gives existing users a different wallet. --- @@ -685,7 +690,8 @@ App.tsx # Web3AuthProvider + screens using hooks | `LOGIN_PROVIDER` | Replace with `AUTH_CONNECTION` | | `OPENLOGIN_NETWORK` | Replace with `WEB3AUTH_NETWORK` | | `loginConfig:` | Remove; use Dashboard + `authConnectionId` | -| `useCoreKitKey` / `useSFAKey` | Remove | +| `useCoreKitKey: true` | Keep if set in v8 | +| `useSFAKey` | Remove | | `://openlogin` | Replace with `://auth` | | `import './globals'` | Remove | | `SolanaWallet` | Replace with `web3Auth.signer` | From f024365f07634c279fbc664dd757a87287786da0 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Tue, 20 Oct 2026 17:12:26 +0530 Subject: [PATCH 2/3] Clarify Flutter clientId for custom JWT connections Co-authored-by: Cursor --- embedded-wallets/sdk/flutter/advanced/custom-authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedded-wallets/sdk/flutter/advanced/custom-authentication.mdx b/embedded-wallets/sdk/flutter/advanced/custom-authentication.mdx index 43ffe882186..be896ec535d 100644 --- a/embedded-wallets/sdk/flutter/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/flutter/advanced/custom-authentication.mdx @@ -56,7 +56,7 @@ After creating the connection, use the following parameters in `AuthConnectionCo | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `authConnection` | Type of sign-in for the connection. For example, `google` for Google OAuth or `custom` for JWT. Mandatory. | | `authConnectionId` | Auth connection ID registered in the Embedded Wallets dashboard. Mandatory. | -| `clientId` | Client ID from your login provider. Mandatory. | +| `clientId` | For OAuth providers such as Google or Auth0, the provider's client ID. For a custom JWT verified with JWKS, such as Supabase or Firebase, your Embedded Wallets project client ID. It is not a JWT claim. Mandatory. | | `name?` | Display name for the connection. If null, the default name is used. | | `description?` | Description for the button. If provided, renders as a full-length button; otherwise, an icon button. | | `groupedAuthConnectionId?` | Grouped auth connection ID. If provided, `authConnectionId` becomes a sub-identifier for the grouped connection. | From 20cc893b066e381d4ded49ee2a02273fdaa00d80 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Tue, 20 Oct 2026 17:43:23 +0530 Subject: [PATCH 3/3] Document the v11 identity token issuer and Citadel JWKS Co-authored-by: Cursor --- embedded-wallets/authentication/id-token.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/embedded-wallets/authentication/id-token.mdx b/embedded-wallets/authentication/id-token.mdx index 7a0e6653c66..f4103bad894 100644 --- a/embedded-wallets/authentication/id-token.mdx +++ b/embedded-wallets/authentication/id-token.mdx @@ -137,7 +137,7 @@ To validate an ID token server-side, use Web3Auth's JWKS endpoint or project-spe Every JWKS-based verification call **must** include both `issuer` and `audience` options: - **`audience`** must equal your **Project Client ID**. Without it, a token issued by Web3Auth for any other project will pass signature verification, because all projects share the same signing infrastructure. -- **`issuer`** must match the Web3Auth endpoint that issued the token (`https://api-auth.web3auth.io` for social logins, `https://authjs.web3auth.io` for external wallets). +- **`issuer`** for a token from `getAuthTokenInfo()` on `@web3auth/modal` v11 is `web3auth.io`. Verify it with `https://api.web3auth.io/citadel-service/.well-known/jwks.json`. Older social tokens use `https://api-auth.web3auth.io` and `https://api-auth.web3auth.io/jwks`. External wallets use `https://authjs.web3auth.io`. **Who is at risk without `audience` validation?** @@ -154,7 +154,11 @@ If your backend matches users by `userId`, `email`, or `authConnectionId` (the c -JWKS Endpoint: `https://api-auth.web3auth.io/jwks` +For `getAuthTokenInfo()` on `@web3auth/modal` v11, the issuer is `web3auth.io` and the JWKS endpoint is `https://api.web3auth.io/citadel-service/.well-known/jwks.json`. + +The EVM public key is the `wallets[]` entry with `type: "web3auth_app_key"` and `curve: "secp256k1"`. The `ed25519` entry is not the EVM key. + +Older social tokens use JWKS endpoint `https://api-auth.web3auth.io/jwks`. ```ts title="login/route.ts" import * as jose from 'jose'