> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turnkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# handleXOauth()

export const NestedParam = ({parentKey, childKey, type, required, description, children}) => {
  const fullKey = `${parentKey}.${childKey}`;
  const anchorId = `body-${fullKey.replace(/\./g, '-')}`;
  return <div className="py-6 border-gray-100 dark:border-gray-800 border-b last:border-b-0">
  <div className="flex font-mono text-sm group/param-head param-head break-all relative" id={anchorId}>
    <div className="flex-1 flex content-start py-0.5 mr-5">
      <div className="flex items-center flex-wrap gap-2">
        <div className="absolute -top-1.5">
          <a href={`#${anchorId}`} className="-ml-[2.1rem] flex items-center opacity-0 border-0 group-hover/param-head:opacity-100 py-2 [.expandable-content_&]:-ml-[2.1rem]" aria-label="Navigate to header">
            <div className="w-6 h-6 text-gray-400 rounded-md flex items-center justify-center zinc-box bg-white ring-1 ring-gray-400/30 dark:ring-gray-700/25 hover:ring-gray-400/60 dark:hover:ring-white/20">
              <svg xmlns="http://www.w3.org/2000/svg" fill="gray" height="12px" viewBox="0 0 576 512">
                <path d="M0 256C0 167.6 71.6 96 160 96h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C98.1 144 48 194.1 48 256s50.1 112 112 112h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C71.6 416 0 344.4 0 256zm576 0c0 88.4-71.6 160-160 160H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c61.9 0 112-50.1 112-112s-50.1-112-112-112H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c88.4 0 160 71.6 160 160zM184 232H392c13.3 0 24 10.7 24 24s-10.7 24-24 24H184c-13.3 0-24-10.7-24-24s10.7-24 24-24z"></path>
              </svg>
            </div>
          </a>
        </div>
        <div className="font-semibold text-primary dark:text-primary-light cursor-pointer overflow-wrap-anywhere">
          <span className="text-gray-500 dark:text-gray-400">{parentKey}.</span>
          {childKey}
        </div>
        <div className="inline items-center gap-2 text-xs font-medium [&_div]:inline [&_div]:mr-2 [&_div]:leading-5">
          <div className="flex items-center px-2 py-0.5 rounded-md bg-gray-100/50 dark:bg-white/5 text-gray-600 dark:text-gray-200 font-medium break-all">
            <span>{type}</span>
          </div>
          {required && <span className="px-2 py-0.5 rounded-md bg-red-100/50 dark:bg-red-400/10 text-red-600 dark:text-red-300 font-medium whitespace-nowrap">
              required
            </span>}
        </div>
      </div>
    </div>
  </div>
  {children && <div className="mt-4">
      <div className="prose prose-sm prose-gray dark:prose-invert">
        {children}
      </div>
    </div>}
</div>;
};

export const H3Bordered = ({text}) => <h3 id={text.toLowerCase()} className="border-b pb-2.5 border-gray-100 dark:border-gray-800">
    {text}
  </h3>;

<p><strong>Package:</strong> <code>react-wallet-kit</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/v2026.3.1/packages/react-wallet-kit/src/providers/client/Types.tsx#L209">react-wallet-kit/src/providers/client/Types.tsx:209</a></p>

<H3Bordered text="Overview" />

Handles the Twitter (X) OAuth 2.0 flow.

<ul>
  <li>This function initiates the OAuth 2.0 PKCE flow with Twitter (X) by redirecting the user to the X authorization page or opening it in a popup window.</li>
  <li>It supports both "popup" and "redirect" flows, determined by the `openInPage` parameter.</li>
  <li>Generates a new ephemeral API key pair and uses its public key as part of the state and a cryptographic nonce to bind the OAuth session.</li>
  <li>Creates a PKCE verifier/challenge pair, storing the verifier in `sessionStorage` for later use in the token exchange.</li>
  <li>Constructs the Twitter (X) OAuth URL with all required parameters, including client ID, redirect URI, response type, scope, PKCE code challenge, nonce, and state.</li>
  <li>The `state` parameter encodes the provider name, flow type, ephemeral public key, and any additional key-value pairs provided in `additionalState`.</li>
  <li>If `openInPage` is true, the current page is redirected to the OAuth URL and the function returns a promise that resolves on redirect or rejects after 5 minutes if no redirect occurs.</li>
  <li>If `openInPage` is false, a popup window is opened for the OAuth flow, and the function returns a promise that resolves when the OAuth code is captured or rejects if the popup is closed or times out.</li>
  <li>On receiving an authorization code, the function exchanges it for an OIDC token via the Turnkey proxy (`proxyOAuth2Authenticate`) using the PKCE verifier, redirect URI, and nonce.</li>
  <li>On successful authentication, the function either calls the provided `onOauthSuccess` callback, triggers the `onOauthRedirect` callback from provider callbacks, or completes the OAuth flow internally by calling `completeOauth`.</li>
  <li>Handles error cases such as missing configuration, popup failures, missing PKCE verifier, or Turnkey proxy failures, throwing a `TurnkeyError` with appropriate error codes.</li>
</ul>

<H3Bordered text="Parameters" />

<ParamField body="params" type="HandleXOauthParams" required={false}>
  <Expandable title="params details">
    <NestedParam parentKey="params" childKey="additionalState" type="Record<string, string>" required={false}>
      Additional key-value pairs to include in the OAuth state parameter for tracking or custom logic.
    </NestedParam>

    <NestedParam parentKey="params" childKey="clientId" type="string" required={false}>
      The Twitter (X) Client ID to use (defaults to the client ID from configuration).
    </NestedParam>

    <NestedParam parentKey="params" childKey="onOauthSuccess" type="object" required={false}>
      Callback function to handle the successful OAuth response (receives `{ oidcToken, providerName }`).

      onOauthSuccess params:

      * oidcToken: The OIDC token issued by Turnkey after exchanging the auth code.
      * providerName: The name of the OAuth provider ("twitter").
    </NestedParam>

    <NestedParam parentKey="params" childKey="openInPage" type="boolean" required={false}>
      Whether to open the OAuth flow in the current page (redirect) or a popup window (default: false).
    </NestedParam>
  </Expandable>
</ParamField>

<H3Bordered text="Response" />

A successful response returns the following fields:

<ResponseField name="returns" type="void" required={true}>
  A promise that resolves when the OAuth flow is successfully initiated and completed, or rejects on error or timeout.
</ResponseField>