How Configuration Works

In v3, your partner record is the source of truth for how your integration looks and behaves — authentication methods, theme, external wallets, links, and more. You manage it in the Developer Portal, and the SDK reads it at runtime. Most settings no longer need to live in your app code. What you’ll learn

Where Para reads each setting from, and how the layers combine
What you can override in code with configOverrides, and what is partner-authoritative
How the SDK enforces resolved configuration with PartnerConfigError
Which paraModalConfig props are deprecated and what replaces them

Where configuration comes from

Para resolves each setting from three layers. A higher layer only overrides the specific fields it sets — everything else falls through to the layer below.

SDK configOverrides   (code, per-instance)        ← highest priority
        ▼
Partner record        (Developer Portal)          ← the source of truth
        ▼
Deprecated ParaModal props (paraModalConfig.*)     ← fallback for un-migrated apps

This is a per-field merge, not all-or-nothing. If your partner record sets an OAuth allowlist but you override only the theme in code, you get your code theme and the partner’s OAuth allowlist.

The partner record (source of truth)

The partner record is fetched from your API key when the SDK initializes. Configure it in the Developer Portal. It governs:

Authentication — OAuth methods, email/phone toggles, 2FA, guest mode, auth layout
Branding & theme — colors, font, border radius, logo, “hide wallet” language
External wallets — supported wallets, connection mode, WalletConnect project ID, app description
App identity & links — display name, homepage/social/support URLs, RPC URL
Other — supported wallet types, account links, balance display

Because it lives on the partner record, you can change any of these in the portal without redeploying your app.

Overriding in code with `configOverrides`

For per-instance overrides, pass configOverrides to ParaProvider. This is the supported, non-deprecated way to override partner config from code — useful when one API key powers multiple brand contexts, or for pointing rpcUrl at a local node during development.

<ParaProvider
  paraClientConfig={{ apiKey: process.env.NEXT_PUBLIC_PARA_API_KEY || "" }}
  configOverrides={{
    themeConfig: {
      foregroundColor: "#007AFF",
      backgroundColor: "#FFFFFF",
    },
    authConfig: {
      oAuthMethods: ["GOOGLE", "APPLE"],
    },
  }}
>
  {children}
</ParaProvider>

configOverrides is typed as Partial<SdkOverridableAppConfig> — the compiler only lets you override fields that are safe to set per-instance.

What you can override

Area	Overridable fields
`themeConfig`	All theme fields (colors, font, border radius, mix ratio, `cssOverrides`)
`authConfig`	`oAuthMethods`, `disableEmailLogin`, `disablePhoneLogin`, `twoFactorAuthEnabled`, `isGuestModeEnabled`
`modalConfig`	`hideWallets`, `authLayout`, `hideLogo`, `disableAddFundsPrompt`
`externalWalletConfig`	`wallets`, `connectionOnly`, `includeWalletVerification`, `createLinkedEmbeddedForExternalWallets`, `walletConnectProjectId`, `appDescription`
`rpcUrl`	The chain RPC URL (handy for local dev)

What is partner-authoritative (cannot be overridden)

These are excluded from SdkOverridableAppConfig at the type level — the SDK cannot weaken them, and they live only on the partner record:

Field	Why
`authConfig.supportedAuthMethods`	Security posture
`supportedWalletTypes`	Security/policy boundary
`supportedAccountLinks`	Security/policy boundary
`balancesConfig`	Partner-level setting
`partnerLinks` (homepage/social/support URLs)	One per project
`appName`	One per project
`farcasterConfig`	Read only by the backend (email templates)

Enforcement: `PartnerConfigError`

The SDK enforces the resolved auth and wallet configuration at its entry points (sign-up/login, OAuth, 2FA setup, guest wallet creation), not just in the modal. If you trigger something that is explicitly disabled, the call throws a PartnerConfigError with a stable .code.

import { PartnerConfigError } from "@getpara/react-sdk";

try {
  await para.createGuestWallets();
} catch (e) {
  if (e instanceof PartnerConfigError && e.code === "GUEST_MODE_DISABLED") {
    // Guest mode is turned off for this partner — handle gracefully.
  }
}

`code`	Thrown when
`EMAIL_LOGIN_DISABLED`	`authConfig.disableEmailLogin` is `true`
`PHONE_LOGIN_DISABLED`	`authConfig.disablePhoneLogin` is `true`
`OAUTH_METHOD_NOT_ALLOWED`	An OAuth method isn’t in the resolved `oAuthMethods` allowlist (`.detail` holds the method)
`TWO_FACTOR_DISABLED`	`authConfig.twoFactorAuthEnabled` is explicitly `false`
`GUEST_MODE_DISABLED`	`authConfig.isGuestModeEnabled` is explicitly `false`

Unset means “not configured”, not “disabled.” A field that has never been set stays permissive; the gate only fires on an explicit choice (a true disable flag, an explicit false opt-in flag, or a defined OAuth allowlist). This keeps upgrades non-breaking: restrictions take effect once you configure them in the portal or with configOverrides, not before.

The default <ParaModal /> hides disabled options, so you typically only hit PartnerConfigError from custom UI or direct SDK calls, or when a deprecated fallback conflicts with higher-priority resolved config.

Deprecated: configuring via `paraModalConfig` props

These paraModalConfig props still work, but they’re the lowest-priority fallback and are deprecated — they’ll be removed in the next major release. Each emits a one-time console warning. Configure them on the partner record (Developer Portal) instead, or use configOverrides for per-instance overrides.

Deprecated `paraModalConfig` prop	Configure instead via
`oAuthMethods`	Portal authentication / `configOverrides.authConfig.oAuthMethods`
`disableEmailLogin`, `disablePhoneLogin`	Portal authentication / `configOverrides.authConfig.*`
`twoFactorAuthEnabled`	Portal authentication / `configOverrides.authConfig.twoFactorAuthEnabled`
`isGuestModeEnabled`	Portal authentication / `configOverrides.authConfig.isGuestModeEnabled`
`authLayout`	Portal authentication / `configOverrides.modalConfig.authLayout`
`hideWallets`	Portal / `configOverrides.modalConfig.hideWallets`
`theme`	Portal branding / `configOverrides.themeConfig`
`logo`	Portal branding / `configOverrides.modalConfig.logo`
`supportedAccountLinks`	Portal (partner-authoritative)
`balances`	Portal (partner-authoritative)

Because props are the lowest layer, a value you set in code is overridden by the same setting on the partner record. If a prop seems to have no effect, check whether the partner record sets it.

See the Migration Guide for step-by-step migration of each prop.

Next steps

Style the Modal — theme, fonts, and CSS overrides
Customization Basics — the full paraModalConfig reference
Migrating to v3 — what changed and how to move config to the partner record

Documentation Index

​Where configuration comes from

​The partner record (source of truth)

​Overriding in code with configOverrides

​What you can override

​What is partner-authoritative (cannot be overridden)

​Enforcement: PartnerConfigError

​Deprecated: configuring via paraModalConfig props

​Next steps

Where configuration comes from

The partner record (source of truth)

Overriding in code with `configOverrides`

What you can override

What is partner-authoritative (cannot be overridden)

Enforcement: `PartnerConfigError`

Deprecated: configuring via `paraModalConfig` props

Next steps