{/* Iframe will be inserted here */}

); } ``` For an example in context, we highly recommend taking a look at the [wallet-export-sign example app](https://github.com/tkhq/sdk/blob/0af0303ca4714cf65f5177cdb05f824877713d2a/examples/wallet-export-sign/src/components/Export.tsx#L62-L107). ### Step 2: Create the Export Caller (Backend or Client-side) The export call can be made from a backend API route or a trusted client-side environment. The example below shows a server-side API route; if you call from the client, avoid exposing key material. ```typescript theme={"system"} // pages/api/exportWalletAccount.ts import type { NextApiRequest, NextApiResponse } from "next"; import { Turnkey } from "@turnkey/sdk-server"; export default async function handler( req: NextApiRequest, res: NextApiResponse ) { const { walletAccountAddress, targetPublicKey } = req.body; const turnkeyClient = new Turnkey({ apiBaseUrl: process.env.NEXT_PUBLIC_BASE_URL!, apiPublicKey: process.env.API_PUBLIC_KEY!, apiPrivateKey: process.env.API_PRIVATE_KEY!, defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!, }); const { address, exportBundle } = await turnkeyClient .apiClient() .exportWalletAccount({ organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!, address: walletAccountAddress, targetPublicKey: targetPublicKey, }); res.status(200).json({ address, exportBundle }); } ``` ### Step 3: Export a Private Key to the Iframe ```typescript theme={"system"} import { KeyFormat } from "@turnkey/iframe-stamper"; import axios from "axios"; async function exportKeyToIframe( iframeStamper: IframeStamper, walletAccountAddress: string, organizationId: string ) { // Step 3a: Get or initialize the embedded key let embeddedKey = await iframeStamper.getEmbeddedPublicKey(); if (!embeddedKey) { embeddedKey = await iframeStamper.initEmbeddedKey(); } // Step 3b: Request export bundle from your export caller const response = await axios.post("/api/exportWalletAccount", { walletAccountAddress, targetPublicKey: embeddedKey, }); // Step 3c: Inject the bundle into the iframe const injected = await iframeStamper.injectKeyExportBundle( response.data.exportBundle, organizationId, KeyFormat.Hexadecimal, // or KeyFormat.Solana for Solana-formatted keys walletAccountAddress // Required for multi-key support ); if (!injected) { throw new Error("Failed to inject export bundle"); } // The key is now stored in-memory within the iframe // The embedded key remains available for additional exports } ``` ### Step 4: Sign Messages ```typescript theme={"system"} import { MessageType } from "@turnkey/iframe-stamper"; async function signMessage( iframeStamper: IframeStamper, message: string, walletAccountAddress: string ): Promise { const signature = await iframeStamper.signMessage( { message, type: MessageType.Solana, }, walletAccountAddress // Required when multiple keys are loaded ); return signature; // Returns hex-encoded signature } ``` ### Step 5: Sign Transactions ```typescript theme={"system"} import { TransactionType } from "@turnkey/iframe-stamper"; async function signTransaction( iframeStamper: IframeStamper, serializedTransaction: string, // Hex-encoded transaction bytes walletAccountAddress: string ): Promise { const signedTransaction = await iframeStamper.signTransaction( { transaction: serializedTransaction, type: TransactionType.Solana, }, walletAccountAddress ); return signedTransaction; // Returns hex-encoded signed transaction } ``` ## Multi-Key Support One of the key capabilities of client-side signing is the ability to load and manage multiple private keys simultaneously within the iframe. ### Loading Multiple Keys Since the embedded key persists across bundle injections, you can export multiple keys using the same embedded key (as long as it hasn't expired): ```typescript theme={"system"} async function loadMultipleKeys( iframeStamper: IframeStamper, addresses: string[], organizationId: string ) { // Get or initialize the embedded key once let embeddedKey = await iframeStamper.getEmbeddedPublicKey(); if (!embeddedKey) { embeddedKey = await iframeStamper.initEmbeddedKey(); } for (const address of addresses) { const response = await axios.post("/api/exportWalletAccount", { walletAccountAddress: address, targetPublicKey: embeddedKey, // Same embedded key for all exports }); await iframeStamper.injectKeyExportBundle( response.data.exportBundle, organizationId, KeyFormat.Hexadecimal, address // Each key is stored by its address ); } } ``` ### Signing with Different Keys ```typescript theme={"system"} // Sign with the first address const sig1 = await iframeStamper.signMessage( { message: "Hello", type: MessageType.Solana }, "address1..." ); // Sign with the second address const sig2 = await iframeStamper.signMessage( { message: "World", type: MessageType.Solana }, "address2..." ); ``` ### Clearing Keys ```typescript theme={"system"} // Clear a specific key await iframeStamper.clearEmbeddedPrivateKey("address1..."); // Clear all keys (no address parameter) await iframeStamper.clearEmbeddedPrivateKey(); ``` ## Key Lifecycle and Expiration Understanding the key lifecycle is important for building reliable applications. ### Embedded Key (P-256 ECDH) * **Storage**: localStorage within the iframe * **TTL**: 48 hours (default) * **Purpose**: Decrypt incoming export bundles via HPKE * **Behavior**: Persists across bundle injections - the same embedded key can decrypt multiple export bundles until it expires or is explicitly cleared ### In-Memory Private Keys * **Storage**: JavaScript memory only (never persisted) * **TTL**: 24 hours * **Purpose**: Sign messages and transactions * **Behavior**: Lost on page reload, cleared on expiration ### Handling Expiration ```typescript theme={"system"} // Re-export flow when keys expire or page reloads async function ensureKeyLoaded( iframeStamper: IframeStamper, address: string, organizationId: string ) { try { // Attempt to sign a test message await iframeStamper.signMessage( { message: "test", type: MessageType.Solana }, address ); } catch (error) { // Key not found or expired - re-export await exportKeyToIframe(iframeStamper, address, organizationId); } } ``` ## Key Formats | Format | Description | Use Case | | ----------------------- | ------------------------------------------------ | ------------------------------ | | `KeyFormat.Solana` | Base58-encoded 64-byte format (private + public) | Phantom, Solflare, Solana keys | | `KeyFormat.Hexadecimal` | 64 hexadecimal digits (32 bytes) | Non-Solana | ## Complete Example Here's a complete React component demonstrating the full flow: ```typescript theme={"system"} import { IframeStamper, KeyFormat, MessageType, TransactionType, } from "@turnkey/iframe-stamper"; import { useEffect, useState } from "react"; import axios from "axios"; const IFRAME_CONTAINER_ID = "turnkey-iframe-container"; const IFRAME_ELEMENT_ID = "turnkey-iframe"; interface Props { organizationId: string; walletAccountAddress: string; } export function ClientSideSigner({ organizationId, walletAccountAddress, }: Props) { const [iframeStamper, setIframeStamper] = useState( null ); const [isKeyLoaded, setIsKeyLoaded] = useState(false); const [message, setMessage] = useState("Hello, Turnkey!"); const [signature, setSignature] = useState(""); // Initialize iframe useEffect(() => { const stamper = new IframeStamper({ iframeUrl: process.env.NEXT_PUBLIC_EXPORT_SIGN_IFRAME_URL!, iframeContainer: document.getElementById(IFRAME_CONTAINER_ID), iframeElementId: IFRAME_ELEMENT_ID, }); stamper .init() .then(() => setIframeStamper(stamper)) .catch(console.error); return () => stamper.clear(); }, []); // Export key to iframe const exportKey = async () => { if (!iframeStamper) return; let embeddedKey = await iframeStamper.getEmbeddedPublicKey(); if (!embeddedKey) { embeddedKey = await iframeStamper.initEmbeddedKey(); } const response = await axios.post("/api/exportWalletAccount", { walletAccountAddress, targetPublicKey: embeddedKey, }); await iframeStamper.injectKeyExportBundle( response.data.exportBundle, organizationId, KeyFormat.Hexadecimal, walletAccountAddress ); setIsKeyLoaded(true); }; // Sign message const handleSignMessage = async () => { if (!iframeStamper || !isKeyLoaded) return; const sig = await iframeStamper.signMessage( { message, type: MessageType.Solana }, walletAccountAddress ); setSignature(sig); }; return (

{!isKeyLoaded ? ( ) : (

setMessage(e.target.value)}
          />
          <button onClick={handleSignMessage}>Sign Message</button>
          {signature && <pre>Signature: {signature}</pre>}
        </div>
      )}
    </div>
  );
}
```

## Troubleshooting

### "Iframe not ready"

Ensure `init()` has completed before calling other methods. The iframe needs to load and establish the MessageChannel connection.

### "Key not found for address"

* Verify the address is exactly as provided during `injectKeyExportBundle` (case-sensitive)
* Check if the key has expired (24-hour TTL)
* Ensure the page hasn't been reloaded (keys are in-memory only)

### "Embedded key not found"

The embedded key may have expired (48-hour TTL) or been explicitly cleared. Call `initEmbeddedKey()` to create a new one.

### "Organization ID does not match"

The bundle was created for a different organization. Ensure your backend uses the same organization ID as passed to `injectKeyExportBundle`.

## Best Practices

1. **Always pass the address parameter**: When using multi-key support, always specify which address to sign with
2. **Reuse the embedded key**: The embedded key persists across bundle injections, so you can export multiple keys without re-initializing
3. **Handle page reloads**: Implement re-export logic since in-memory keys are lost on reload (the embedded key survives in localStorage)
4. **Monitor key expiration**: Track when keys will expire - embedded key (48h), in-memory keys (24h)
5. **Use appropriate key formats**: Use `KeyFormat.Solana` for Solana keys

## Reference

### IframeStamper Methods

| Method                                                    | Description                            |
| --------------------------------------------------------- | -------------------------------------- |
| `init()`                                                  | Insert iframe and establish connection |
| `clear()`                                                 | Remove iframe and clean up resources   |
| `getEmbeddedPublicKey()`                                  | Get current embedded key's public key  |
| `initEmbeddedKey()`                                       | Create new embedded key                |
| `clearEmbeddedKey()`                                      | Clear the embedded key                 |
| `injectKeyExportBundle(bundle, orgId, format?, address?)` | Inject private key into iframe         |
| `signMessage(message, address?)`                          | Sign a message                         |
| `signTransaction(transaction, address?)`                  | Sign a transaction                     |
| `clearEmbeddedPrivateKey(address?)`                       | Clear in-memory keys                   |

### Supported Operations

| Operation           | Solana | Ethereum |
| ------------------- | ------ | -------- |
| Message signing     | Yes    | Planned  |
| Transaction signing | Yes    | Planned  |

## Additional Resources

* [Example: wallet-export-sign](https://github.com/tkhq/sdk/tree/main/examples/wallet-export-sign) - Sample Next.js app
* [@turnkey/iframe-stamper](https://github.com/tkhq/sdk/tree/main/packages/iframe-stamper) - Package source code
* [export-and-sign iframe](https://github.com/tkhq/frames/tree/main/export-and-sign) - Iframe implementation

# Create a User Passkey Session
Source: https://docs.turnkey.com/embedded-wallets/code-examples/create-passkey-session

A passkey session is an expiring session enabled by an initial passkey authentication. You could think of this as a "lightning mode" of sorts: creating a passkey session allows users to authenticate subsequent requests touch-free. Under the hood, this is powered by our [indexedDbStamper](/sdks/advanced/indexed-db-stamper). These sessions are enabled by creating a short-lived embedded API key in the browser, stored in localStorage, and cryptographically scoped to a public key generated by IndexedDB.

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](https://docs.turnkey.com/generated-docs/formatted/react-wallet-kit/client-context-type-login-with-passkey) for the updated packages.

By calling `loginWithPasskey()`, the SDK stores the session and active client in localStorage. The signing key material remains securely stored in the browser’s IndexedDB and is never extractable. Turnkey uses this public key to scope and encrypt the session to the appropriate user.

## Steps using `@turnkey/sdk-react`

This process is made seamless by leveraging our [React package](/sdks/react). Read on for a non-React implementation below.

<Steps>
  <Step title="Initialize the React Provider">
    ```js theme={"system"}
    import { TurnkeyProvider } from "@turnkey/sdk-react";

const turnkeyConfig = {
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
      rpId: process.env.RPID,
    };

...

<div className="App">
      <TurnkeyProvider config={turnkeyConfig}>
        {/* Your app components */}
      </TurnkeyProvider>
    </div>
    ```
  </Step>

<Step title="Login with a Passkey and Create a Session">
    ```js theme={"system"}
    import { useTurnkey } from "@turnkey/sdk-react";

const { passkeyClient, indexedDbClient } = useTurnkey();

await indexedDbClient.init();
    const publicKey = await indexedDbClient.getPublicKey();

await passkeyClient.loginWithPasskey({
      publicKey,
      sessionType: "SESSION_TYPE_READ_WRITE", // or "SESSION_TYPE_READ_ONLY"
      expirationSeconds: 900,
    });
    ```
  </Step>

<Step title="Use the session to make requests">
    ```js theme={"system"}
    const { getActiveClient } = useTurnkey();
    const client = await getActiveClient();

const whoami = await client.getWhoami({
      organizationId: <your-org-id>,
    });
    ```

`getActiveClient()` returns the currently active client (e.g. IndexedDb-backed), refreshing automatically if needed.
  </Step>
</Steps>

## Alternative Steps (non-React)

<Steps>
  <Step title="Initialize the Passkey and IndexedDB Clients">
    ```js theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";

const turnkey = new Turnkey({
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
    });

const passkeyClient = turnkey.passkeyClient();
    const indexedDbClient = turnkey.indexedDbClient();

await indexedDbClient.init();
    ```
  </Step>

<Step title="Login with a Passkey and Create a Session">
    ```js theme={"system"}
    const publicKey = await indexedDbClient.getPublicKey();

await passkeyClient.loginWithPasskey({
      publicKey,
      sessionType: "SESSION_TYPE_READ_WRITE", // or "SESSION_TYPE_READ_ONLY"
      expirationSeconds: 900,
    });
    ```
  </Step>

<Step title="Use the session to make requests">
    ```js theme={"system"}
    const whoami = await turnkey.getWhoami({
      organizationId: <your-org-id>,
    });
    ```

Once `loginWithPasskey` completes, the session is stored in localStorage and all requests are signed using the IndexedDb-backed keypair.
  </Step>
</Steps>

# Create a Sub-Org with a Passkey User
Source: https://docs.turnkey.com/embedded-wallets/code-examples/create-sub-org-passkey

In this guide, we'll walk through the process of creating a new end user with a passkey.

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](https://docs.turnkey.com/sdks/react/sub-organization-customization) for the updated packages.

## Overview

Generally, these new users will take the form of a [Turnkey Sub-Organization](/concepts/sub-organizations). This process involves using the following Turnkey SDK packages:

1. [`@turnkey/sdk-server`](https://www.npmjs.com/package/@turnkey/sdk-server): Used on the server-side to leverage the parent organization's public/private API key pair to create the new user's sub-organization.
2. [`@turnkey/sdk-browser`](https://www.npmjs.com/package/@turnkey/sdk-browser): Used on the client-side to complete the email recovery process by adding an end-user passkey.
3. [`@turnkey/sdk-react`](https://www.npmjs.com/package/@turnkey/sdk-react): Used for Next.js applications to initialize the Turnkey SDK.

The process of creating a new sub-organization is split between client-side and server-side operations to prevent exposing the parent organization's private API key.

<Note>
  For a refresher on the relationship between your application's end users and Turnkey Sub-Organizations, see [this page](/embedded-wallets/overview#how-it-works) for more.
</Note>

## Implementation

### Initialize the Turnkey SDK on the Browser

<Tabs>
  <Tab title="Next.js">
    Wrap the root layout of your application with the `TurnkeyProvider` providing the required configuration options. This allows you to use the Turnkey client throughout your app via the `useTurnkey()` hook.

```tsx app/layout.tsx theme={"system"}
    import { TurnkeyProvider } from "@turnkey/sdk-react";

export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <html>
          <body>
            <TurnkeyProvider
              config={{
                rpId: process.env.NEXT_PUBLIC_TURNKEY_RP_ID,
                apiBaseUrl: process.env.NEXT_PUBLIC_TURNKEY_API_BASE_URL,
                defaultOrganizationId:
                  process.env.NEXT_PUBLIC_ORGANIZATION_ID,
              }}
            >
              {children}
            </TurnkeyProvider>
          </body>
        </html>
      );
    }
    ```

<Note>
      The `NEXT_PUBLIC_ORGANIZATION_ID` should be set to the parent organization ID which can be found in the [Turnkey Dashboard](https://app.turnkey.com/dashboard).

The `NEXT_PUBLIC_TURNKEY_RP_ID` should be set to your application's desired relying party ID; this is typically your domain, or localhost if developing locally. See [this page](/authentication/passkeys/options#rp) for more details.
    </Note>
  </Tab>

<Tab title="TypeScript">
    ```tsx src/turnkey.ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";

// Initialize the Turnkey SDK with your organization ID and API base URL
    const turnkeyBrowser = new Turnkey({
      rpId: process.env.TURNKEY_RP_ID,
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
    });
    ```

<Note>
      The `TURNKEY_ORGANIZATION_ID` should be set to the parent organization ID which can be found in the [Turnkey Dashboard](https://app.turnkey.com/dashboard).

The `TURNKEY_RP_ID` should be set to your application's desired relying party ID; this is typically your domain, or localhost if developing locally. See [this page](/authentication/passkeys/options#rp) for more details.
    </Note>
  </Tab>
</Tabs>

### Initialize the Passkey Client

Next, we'll initialize the `passkeyClient`, which will enable your application to interact with passkeys.

<Tabs>
  <Tab title="Next.js">
    We add the `"use client"` directive to the Recovery component to as react hooks can only be used client-side.

```tsx app/create-suborg.tsx theme={"system"}
    "use client";

import { useTurnkey } from "@turnkey/sdk-react";

export default function CreateSubOrganization() {
      const { passkeyClient } = useTurnkey();

return <div>{/* ... rest of the code */}</div>;
    }
    ```
  </Tab>

<Tab title="TypeScript">
    ```tsx src/create-suborg.ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";

// Initialize the Turnkey SDK with your organization credentials
    const turnkey = new Turnkey({
      rpId: process.env.TURNKEY_RP_ID, // Your relying party ID
      apiBaseUrl: process.env.TURNKEY_API_BASE_URL, // Turnkey API base URL
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID, // Your parent organization ID
    });

// Initialize the Passkey Client
    const passkeyClient = turnkey.passkeyClient();

// We'll add more functionality here in the following steps
    ```
  </Tab>
</Tabs>

### Create User Passkey

In order to create a new passkey for a user, you can call the `createUserPasskey` SDK function. Calling this method will prompt the user to create a passkey, which will be securely stored by their browser. This credential will be associated with the user's account (sub-organization) and used for future authentication. Once the credential is created, we'll use it in the next step to create a new sub-organization that corresponds to the user.

<Note>
  The result of `createUserPasskey` includes an encoded challenge and attestation. The encoded challenge ensures the request is fresh and legitimate, while the attestation verifies the authenticity of the device creating the credential. For more information on how passkeys work, including details on the challenge and attestation objects, you can refer to the [Passkeys Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API#passkeys).
</Note>

<Tabs>
  <Tab title="Next.js">
    ```tsx app/create-suborg.tsx theme={"system"}
    // ... previous code

export default function CreateSubOrganization() {
      const { passkeyClient } = useTurnkey();

const createNewPasskey = async () => {
        const credential = await passkeyClient?.createUserPasskey({
          publicKey: {
            // This is the name of the passkey that will be displayed to the user
            rp: {
              name: "Wallet Passkey",
            },
            user: {
              // We can use the username as the name and display name
              name: "Default User Name",
              displayName: "Default User Name",
            },
          },
        });

// we'll use this credential in the next step to create a new sub-organization
        return credential;
      };

// ... rest of the code

return (/* ... */);
    }
    ```
  </Tab>

<Tab title="TypeScript">
    ```tsx src/create-suborg.ts theme={"system"}
    // ... previous code

const createNewPasskey = async () => {
      const credential = await passkeyClient?.createUserPasskey({
        publicKey: {
          // This is the name of the passkey that will be displayed to the user
          rp: {
            name: "Wallet Passkey",
          },
          user: {
            // We can use the username as the name and display name
            name: "Default User Name",
            displayName: "Default User Name",
          },
        },
      });

// we'll use this credential in the next step to create a new sub-organization
      return credential;
    };
    ```
  </Tab>
</Tabs>

### Initialize the Turnkey SDK on the Server

Initialize the Turnkey SDK on the **server-side** using the `@turnkey/sdk-server` package. This allows you to use the parent organization's public/private API key pair to create sub-organizations.

<Tabs>
  <Tab title="Next.js">
    For Next.js, add the `"use server"` directive at the top of the file where you're initializing the Turnkey server client. This will ensure that the function is executed on the server-side and will have access to the server-side environment variables e.g. your parent organization's public/private API key pair. For more information on Next.js server actions, see the Next.js documentation on [Server Actions and Mutations](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations).

```tsx app/actions.ts theme={"system"}
    "use server";

import { Turnkey } from "@turnkey/sdk-server";

// Initialize the Turnkey Server Client on the server-side
    const turnkeyServer = new Turnkey({
      apiBaseUrl: "https://api.turnkey.com",
      apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY,
      apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY,
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
    }).apiClient();
    ```
  </Tab>

<Tab title="TypeScript">
    ```tsx src/turnkey.ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-server";

### Create a Function for Sub-Org Creation

Next we'll create a new function called `createSubOrganization` that will be used to create a new sub-organization from the server-side. This method will be called from the client-side with the end-user's details.

<Tabs>
  <Tab title="Next.js">
    We export the `createSubOrganization` server action to be called from the client-side.

```tsx app/actions.tsx theme={"system"}
    import { DEFAULT_ETHEREUM_ACCOUNTS } from "@turnkey/sdk-browser";

// ... previous code

type TAttestation = {
      credentialId: string;
      clientDataJson: string;
      attestationObject: string;
      transports: (
        | "AUTHENTICATOR_TRANSPORT_BLE"
        | "AUTHENTICATOR_TRANSPORT_INTERNAL"
        | "AUTHENTICATOR_TRANSPORT_NFC"
        | "AUTHENTICATOR_TRANSPORT_USB"
        | "AUTHENTICATOR_TRANSPORT_HYBRID"
      )[];
    };

export const createSubOrganization = async (
      email: string,
      credential: string,
      attestation: string,
    ) => {
      const createSubOrgResponse = await turnkeyServer.createSubOrganization({
        subOrganizationName: "My New Suborg",
        rootUsers: [
          {
            userName: "Default User Name",
            userEmail: email,
            apiKeys: [],
            authenticators: [
              {
                authenticatorName: "Default Passkey",
                challenge: challenge,
                attestation: attestation,
              },
            ],
            oauthProviders: [],
          },
        ],
        rootQuorumThreshold: 1,
        wallet: {
          walletName: "Default Wallet",
          accounts: DEFAULT_ETHEREUM_ACCOUNTS,
        },
      });

return createSubOrgResponse;
    };
    ```
  </Tab>

<Tab title="TypeScript">
    ```tsx src/turnkey-server.ts theme={"system"}
    /// ... previous code

return createSubOrgResponse;
    };
    ```
  </Tab>
</Tabs>

### Complete Create Sub-Organization

At this stage, we create the sub-organization using the **server-side** function we created in the previous step.

<Tabs>
  <Tab title="Next.js">
    <Steps>
      <Step title="Import the server action">
        ```tsx app/create-suborg.tsx theme={"system"}
        import { createSubOrganization } from "./actions";
        ```
      </Step>

<Step title="Call createSubOrganization with the end-user's details">
        ```tsx app/create-suborg.tsx theme={"system"}
        // ...

import { useForm } from "react-hook-form";

type TSubOrgFormData = {
          email: string;
        };

export default function CreateSubOrganization() {
          // ...

// Use form handler for suborg creation
          const { register: subOrgFormRegister, handleSubmit: subOrgFormSubmit } =
            useForm<TSubOrgFormData>();

// Maintain state
          const [createSubOrganizationResponse, setCreateSubOrganizationResponse] =
            useState(null);

const createSubOrg = async (data: TSubOrgFormData) => {
            const { encodedChallenge: challenge, attestation } =
              await createNewPasskey();

const createSubOrganizationResponse = await createSubOrganization(
              data.email,
              challenge,
              attestation,
            );

setCreateSubOrganizationResponse(createSubOrganizationResponse);
          };

return (
            <div>
              {createSubOrganizationResponse ? (
                <h2>You've created a sub-organization!</h2>
              ) : (
                <form onSubmit={subOrgFormSubmit(createSubOrg)}>
                  <label>
                    Email
                    <input {...subOrgFormRegister("email")} placeholder="User Email" />
                  </label>
                  <input type="submit" value="Create new sub-organization" />
                </form>
              )}
            </div>
          );
        }
        ```

<Accordion title="create-suborg.tsx">
          ```tsx theme={"system"}
          "use client";

import { useState } from "react";
          import { useTurnkey } from "@turnkey/sdk-react";
          import { useForm } from "react-hook-form";

// Import the createSubOrganization server action
          import { createSubOrganization } from "./actions";

type TSubOrgFormData = {
          email: string;
          };

type TAttestation = {
          credentialId: string;
          clientDataJson: string;
          attestationObject: string;
          transports: (
            | "AUTHENTICATOR_TRANSPORT_BLE"
            | "AUTHENTICATOR_TRANSPORT_INTERNAL"
            | "AUTHENTICATOR_TRANSPORT_NFC"
            | "AUTHENTICATOR_TRANSPORT_USB"
            | "AUTHENTICATOR_TRANSPORT_HYBRID"
          )[];
          };

export default function CreateSubOrganization() {
          const { passkeyClient } = useTurnkey();

// Use form handler for suborg creation
          const { register: subOrgFormRegister, handleSubmit: subOrgFormSubmit } =
            useForm<TSubOrgFormData>();

// Maintain state
          const [createSubOrganizationResponse, setCreateSubOrganizationResponse] =
            useState(null);

const createNewPasskey = async () => {
            const credential = await passkeyClient?.createUserPasskey({
              publicKey: {
                // This is the name of the passkey that will be displayed to the user
                rp: {
                  name: "Wallet Passkey",
                },
                user: {
                  // We can use the username as the name and display name
                  name: "Default User Name",
                  displayName: "Default User Name",
                },
              },
            });

// we'll use this credential in the next step to create a new sub-organization
            return credential;
          };

const createSubOrg = async (data: TSubOrgFormData) => {
            const { encodedChallenge: challenge, attestation } =
              await createNewPasskey();

const createSubOrganizationResponse = await createSubOrganization(
              data.email,
              challenge,
              attestation,
            );

setCreateSubOrganizationResponse(createSubOrganizationResponse);
          };

<Tab title="Next.js">
    <Steps>
      <Step title="Import the server action">
        ```tsx app/create-suborg.tsx theme={"system"}
        import { createSubOrganization } from "./turnkey-server";
        ```
      </Step>

<Step title="Call createSubOrganization with the end-user's details">
        ```tsx src/turnkey.ts theme={"system"}
        import { createSubOrganization } from "./turnkey-server";

// ... rest of the code

const createSubOrganizationResponse = await createSubOrganization(
          email,
          attestation,
          challenge,
        );
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Examples

A few mini examples where sub-orgs are created with passkeys, see the following:

# Create a User with Email Only
Source: https://docs.turnkey.com/embedded-wallets/code-examples/create-user-email

This example demonstrates how to create a sub organization using just an end-user's email: passkeys not required! Note that this flow does not require emails to be verified.

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](https://docs.turnkey.com/sdks/react/sub-organization-customization) for the updated packages.

<Steps>
  <Step title="Initialize Turnkey">
    ```JavaScript theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";

const turnkey = new Turnkey({
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
    });
    ```
  </Step>

<Step title="Configure the Sub Organization for the User">
    ```JavaScript theme={"system"}
    import { DEFAULT_ETHEREUM_ACCOUNTS } from "@turnkey/sdk-browser;"

const subOrganizationConfig = {
      subOrganizationName: <subOrganizationName>,
      rootUsers: [{
        userName: <userEmail>,
        userEmail: <userEmail>,
        apiKeys: [],
        authenticators: [],
        oauthProviders: []
      }],
      rootQuorumThreshold: 1,
      wallet: {
        walletName: <walletName>,
        accounts: DEFAULT_ETHEREUM_ACCOUNTS
      }
    };
    ```
  </Step>

<Step title="Call createSubOrganization from your backend">
    ```JavaScript theme={"system"}
    await turnkey.serverSign("createSubOrganization", [subOrganizationConfig]);
    ```

This is all that is needed to create a user without any authentication credential other than their email address, in the [login](/embedded-wallets/code-examples/authenticate-user-email) flow you can see how to then authenticate the user after their `subOrganization` is created.
  </Step>
</Steps>

# Export Wallet or Private Key
Source: https://docs.turnkey.com/embedded-wallets/code-examples/export

This is a guide to exporting your wallet or private key from Turnkey. For more information about the security of this flow, check out [Enclave secure channels](/security/enclave-secure-channels).

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](/sdks/react/using-embedded-wallets#importing-and-exporting-wallets) for the updated packages.

## Implementation guides

Follow along with the Turnkey CLI, Embedded iframe, NodeJS, and Local Storage guides.

### CLI

Install the latest version of Turnkey CLI to access the new import functionality. You can find detailed instructions for installation [here](https://github.com/tkhq/tkcli).

#### Steps

<Steps>
  <Step title="Export a wallet (Turnkey activity)">
    ```bash theme={"system"}
    turnkey wallets export --name "New Wallet" -k <your Turnkey API key name> --organization <your organization ID> --export-bundle-output <path to your export bundle> --host api.turnkey.com
    ```

* The `--export-bundle-output` flag (required) is the desired output file path for the “encrypted bundle” that will be returned by Turnkey. This bundle contains the encrypted key material.
  </Step>

<Step title="Decrypt the bundle">
    ```bash theme={"system"}
    turnkey decrypt --export-bundle-input <path to your export bundle> --organization <your organization ID> --signer-quorum-key 04bce6666ca6c12e0e00a503a52c301319687dca588165b551d369496bd1189235bd8302ae5e001fde51d1e22baa1d44249f2de9705c63797316fc8b7e3969a665 --encryption-key-name <your local encryption key>

>> "<redacted mnemonic>"
    ```

Congrats! You've exported your wallet 🎉
  </Step>
</Steps>

#### Private Key support

<Steps>
  <Step title="Export a private key (Turnkey activity)">
    ```bash theme={"system"}
    turnkey private-keys export --name "New Private Key" --encryption-key-name <your local encryption key> --organization <your organization ID> --export-bundle-output <path to your export bundle> --host api.turnkey.com
    ```

>> "<redacted private key>"
    ```

* The `--export-bundle-input` flag (required) is the file path for the “encrypted bundle” (from the previous step) that will be decrypted.
    * The `--plaintext-output` flag (optional) is a filepath for the decrypted plaintext to be written to.
    * The `--signer-quorum-key` flag (optional) is the public key of Turnkey's signer enclave. This is a static value.
    * The `--solana-address` flag (optional) is the solana address corresponding to the private key you're exporting. This will export the private key in a format compatible with most solana wallets (e.g. phantom). If unset, the resulting private key will be plain hex.
    * The `--encryption-key-name` flag (optional) is a local encryption key. This is required for import and export using the CLI. A new one can be generated using `turnkey generate encryption-key`. See `turnkey generate --help` for more details.

Congrats! You've exported your private key 🎉
  </Step>
</Steps>

#### Wallet Account support

<Steps>
  <Step title="Export a wallet account (Turnkey activity)">
    ```bash theme={"system"}
    turnkey wallets accounts export --address "<wallet account address>" -k <your API key name> --organization <your organization ID> --export-bundle-output <path to your export bundle> --host api.turnkey.com
    ```

>> "<redacted private key>"
    ```

Congrats! You've exported your private key 🎉
  </Step>
</Steps>

### Embedded iframe

* We have released open-source code to create target encryption keys and decrypt exported wallet mnemonics. We've deployed a static HTML page hosted on `export.turnkey.com` meant to be embedded as an iframe element (see the code [here](https://github.com/tkhq/frames)). This ensures the mnemonics are encrypted to keys that the user has access to, but that your organization does not (because they live in the iframe, on a separate domain).
* We have also built a package to help you insert this iframe and interact with it in the context of export: [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper)

In the rest of this guide we'll assume you are using these helpers.

#### Steps

Here's a diagram summarizing the wallet export flow step-by-step
([direct link](/assets/files/wallet_export_steps-5bb19c72eb9596fab8db3b1dcc52e60a.png)):

Let's review these steps in detail:

<Steps>
  <Step>
    When a user on your application clicks "export", display a new export UI. We recommend setting this export UI as a new hosted page of your application that contains language explaining the security best practices users should follow once they've successfully exported their wallet. Remember: once the wallet has been exported, Turnkey can no longer ensure its security.

While the UI is in a loading state, your application uses [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) to insert a new iframe element:

```ts theme={"system"}
    const iframeStamper = new IframeStamper({
    iframeUrl: "https://export.turnkey.com",
    // Configure how the iframe element is inserted on the page
    iframeContainer: yourContainer,
    iframeElementId: "turnkey-iframe",
    });

// Inserts the iframe in the DOM. This creates the new encryption target key
    const publicKey = await iframeStamper.init();

// Set state to not display iframe
    let displayIframe = "none";

return (
    // The iframe element can be hidden until the wallet is exported
    <div style={{ display: displayIframe }} />
    );
    ```
  </Step>

<Step>
    Your code receives the iframe public key. Your application prompts the user to
    sign a new `EXPORT_WALLET` activity with the wallet ID and the iframe public
    key in the parameters.
  </Step>

<Step>
    Your application polls for the activity response, which contains an export bundle. Remember: this export bundle is an encrypted mnemonic which can only be decrypted within the iframe.

Need help setting up async polling? Checkout our guide and helper [here](https://github.com/tkhq/sdk/tree/main/packages/http#withasyncpolling-helper).
  </Step>

<Step>
    Your application injects the export bundle into the iframe for decryption and displays the iframe upon success:

```ts theme={"system"}
    // Inject export bundle into iframe
    let success = await iframeStamper.injectWalletExportBundle(exportBundle);

if (success !== true) {
      throw new Error("unexpected error while injecting export bundle");
    }

// If successfully injected, update the state to display the iframe
    iframeDisplay = "block";
    ```

Export is complete! The iframe now displays a sentence of words separated by spaces.

The exported wallet will remain stored within Turnkey’s infrastructure. In your Turnkey dashboard, the exported user Wallet will be flagged as “Exported”.
  </Step>
</Steps>

#### Export as Private Keys

Turnkey also supports exporting Wallet Accounts and Private Keys as private keys.

##### Wallet Accounts

Follow the same steps above for exporting Wallets as mnemonics, but instead use the `EXPORT_WALLET_ACCOUNT` activity and the `injectKeyExportBundle` method from the [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper). You can pass an optional `keyFormat` parameter to `injectKeyExportBundle()` that will apply either hexadecimal or Solana-specific formatting to the private key that is exported in the iframe. The default key format is `HEXADECIMAL`, which is used by MetaMask, MyEtherWallet, Phantom, Ledger, and Trezor for Ethereum keys. For Solana keys, you will need to pass the `SOLANA` key format.

##### Private Keys

Follow the same steps above for exporting Wallets as mnemonics, but instead use the `EXPORT_PRIVATE_KEY` activity and the `injectKeyExportBundle` method from the [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper). You can pass an optional `keyFormat` parameter to `injectKeyExportBundle()` that will apply either hexadecimal or Solana-specific formatting to the private key that is exported in the iframe. The default key format is `HEXADECIMAL`, which is used by MetaMask, MyEtherWallet, Phantom, Ledger, and Trezor for Ethereum keys. For Solana keys, you will need to pass the `SOLANA` key format.

At the end of a successful private key export, the iframe displays a private key.

### NodeJS

A full example Node script can be found here: [https://github.com/tkhq/sdk/tree/main/examples/export-in-node](https://github.com/tkhq/sdk/tree/main/examples/export-in-node)

#### Steps

<Steps>
  <Step title="Initialize a new Turnkey client">
    ```ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-server";
    import { generateP256KeyPair, decryptExportBundle } from "@turnkey/crypto";

...

const turnkeyClient = new Turnkey({
        apiBaseUrl: "https://api.turnkey.com",
        apiPublicKey: process.env.API_PUBLIC_KEY!,
        apiPrivateKey: process.env.API_PRIVATE_KEY!,
        defaultOrganizationId: process.env.ORGANIZATION_ID!,
      });
    ```
  </Step>

<Step title="Generate a new P256 Keypair — this will serve as the target that Turnkey will encrypt key material to">
    ```ts theme={"system"}
    const keyPair = generateP256KeyPair();
    const privateKey = keyPair.privateKey;
    const publicKey = keyPair.publicKeyUncompressed;
    ```
  </Step>

<Step title="Call export (Turnkey activity)">
    ```ts theme={"system"}
    const exportResult = await turnkeyClient.apiClient().exportWallet({
      walletId: walletId,
      targetPublicKey: publicKey,
    });
    ```
  </Step>

Congrats! You've exported your wallet 🎉

The process is largely similar for both private keys and individual wallet accounts.
  </Step>
</Steps>

#### Private Key support

...

<Step title="Call export (Turnkey activity)">
    ```ts theme={"system"}
    const exportResult = await turnkeyClient.apiClient().exportPrivateKey({
      privateKeyId: privateKeyId,
      targetPublicKey: publicKey,
    });
    ```
  </Step>

<Step title="Decrypt encrypted bundle">
    ```ts theme={"system"}
    const decryptedBundle = await decryptExportBundle({
      exportBundle: exportResult.exportBundle,
      embeddedKey: privateKey,
      organizationId,
      returnMnemonic: false,
      keyFormat: "HEXADECIMAL", // optionally specify a key format. Defaults to hexadecimal, but use `SOLANA` to export a private key for use in Solana wallets
    });
    ```

Congrats! You've exported your private key 🎉
  </Step>
</Steps>

#### Wallet Account support

...

<Step title="Call export (Turnkey activity)">
    ```ts theme={"system"}
    const exportResult = await turnkeyClient.apiClient().exportWalletAccount({
      address: address, // your specific wallet account address
      targetPublicKey: publicKey,
    });
    ```
  </Step>

Congrats! You've exported your wallet account 🎉
  </Step>
</Steps>

### Local Storage

If you do not have access to an iframe (e.g. in a mobile context) or would prefer not to use an iframe, using Local Storage is an alternative method. Note that there are security considerations here due to the fact that anyone in control of your domain can access Local Storage variables.

#### Steps

<Steps>
  <Step title="Initialize Turnkey client">
    ```ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";
    import { generateP256KeyPair, decryptExportBundle } from "@turnkey/crypto";

...

const turnkey = new Turnkey({
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
    });
    const passkeyClient = turnkey.passkeyClient();
    ```
  </Step>

<Step title="Generate a new P256 Keypair — this will serve as the target that Turnkey will encrypt key material to">
    ```ts theme={"system"}
    const embeddedKeyPair = generateP256KeyPair();
    const embeddedPrivateKey = keyPair.privateKey;
    const embeddedPublicKey = keyPair.publicKeyUncompressed;
    ```
  </Step>

<Step title="Save the private key in Local Storage">
    ```ts theme={"system"}
    // Storage keys
    const STORAGE_KEYS = {
      EMBEDDED_PRIVATE_KEY: "@turnkey/embedded_private_key",
      EMBEDDED_PUBLIC_KEY: "@turnkey/embedded_public_key",
    };

await LocalStorage.setItem(
      STORAGE_KEYS.EMBEDDED_PRIVATE_KEY,
      embeddedPrivateKey
    );

// Note that the public key can always be derived separately via the `getPublicKey` from `@turnkey/crypto`
    await LocalStorage.setItem(STORAGE_KEYS.EMBEDDED_PUBLIC_KEY, embeddedPublicKey);
    ```
  </Step>

<Step title="Call export (Turnkey activity)">
    4. Call export (Turnkey activity), using the embedded key as the target key for the `exportWallet` activity:

```ts theme={"system"}
    const exportResult = await passkeyClient.exportWallet({
      walletId, // desired wallet ID
      targetPublicKey: embeddedPublicKey,
    });
    ```
  </Step>

<Step title=" Remove embedded key from Local Storage. This is recommended because (1) this key doesn't have to be persistent in the first place, and (2) reduces the risk of pattern detection.">
    ```ts theme={"system"}
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PRIVATE_KEY,
      embeddedPrivateKey
    );
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PUBLIC_KEY,
      embeddedPublicKey
    );
    ```

Congrats! You've exported your wallet 🎉

The process is largely similar for both private keys and individual wallet accounts.
  </Step>
</Steps>

#### Private Key support

...

await LocalStorage.setItem(STORAGE_KEYS.EMBEDDED_PRIVATE_KEY, privateKey);

<Step title="Call export (Turnkey activity)">
    ```ts theme={"system"}
    const exportResult = await passkeyClient.exportPrivateKey({
      privateKeyId, // desired private key ID
      targetPublicKey: publicKey,
    });
    ```
  </Step>

<Step title="Decrypt encrypted bundle">
    ```ts theme={"system"}
    const decryptedBundle = await decryptExportBundle({
      exportBundle: exportResult.exportBundle,
      embeddedKey: privateKey,
      organizationId, // your organization ID (this may be a suborg)
      returnMnemonic: false, // N/A as we're working with a private key, not a wallet
      keyFormat: "HEXADECIMAL", // optionally specify a key format. Defaults to hexadecimal, but use `SOLANA` to export a private key for use in Solana wallets
    });
    ```
  </Step>

<Step title="Remove embedded key from Local Storage. This is recommended because (1) this key doesn't have to be persistent in the first place, and (2) reduces the risk of pattern detection.">
    ```ts theme={"system"}
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PRIVATE_KEY,
      embeddedPrivateKey
    );
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PUBLIC_KEY,
      embeddedPublicKey
    );
    ```

Congrats! You've exported your private key 🎉
  </Step>
</Steps>

#### Wallet Account support

...

await LocalStorage.setItem(STORAGE_KEYS.EMBEDDED_PRIVATE_KEY, privateKey);

<Step title="Call export (Turnkey activity)">
    4. Call export (Turnkey activity), using the embedded key as the target key for the `exportWalletAccount` activity:

```ts theme={"system"}
    const exportResult = await passkeyClient.exportWalletAccount({
      address, // your specific wallet account address
      targetPublicKey: publicKey,
    });
    ```
  </Step>

<Step title="Decrypt encrypted bundle">
    ```ts theme={"system"}
    const decryptedBundle = await decryptExportBundle({
      exportBundle: exportResult.exportBundle,
      embeddedKey: privateKey,
      organizationId, // your organization ID (this may be a suborg)
      returnMnemonic: false, // N/A as we're working with a wallet account, not a wallet
      keyFormat: "HEXADECIMAL", // optionally specify a key format. Defaults to hexadecimal, but use `SOLANA` to export a private key for use in Solana wallets
    });
    ```
  </Step>

<Step title="Remove embedded key from Local Storage. This is recommended because (1) this key doesn't have to be persistent in the first place, and (2) reduces the risk of pattern detection.">
    ```ts theme={"system"}
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PRIVATE_KEY,
      embeddedPrivateKey
    );
    await LocalStorage.removeItem(
      STORAGE_KEYS.EMBEDDED_PUBLIC_KEY,
      embeddedPublicKey
    );
    ```

Congrats! You've exported your wallet account 🎉
  </Step>
</Steps>

## UI customization

Everything is customizable in the import iframe except the sentence of mnemonic words, which is minimally styled: the text is left-aligned and the padding and margins are zero. Here's an example of how you can configure the styling of the iframe.

```ts theme={"system"}
const iframeCss = `
  iframe {
      box-sizing: border-box;
      width: 400px;
      height: 120px;
      border-radius: 8px;
      border-width: 1px;
      border-style: solid;
      border-color: rgba(216, 219, 227, 1);
      padding: 20px;
  }
`;

return (
  <div style={{ display: iframeDisplay }} id="your-container">
    <style>{iframeCss}</style>
  </div>
);
```

## Solana notes

Solana paths do not include an `index`. Creating a wallet account with an index specified could lead to unexpected behavior when exporting and importing into another wallet.

When importing into a multichain wallet such as Phantom, see [this guide](https://help.phantom.app/hc/en-us/articles/12988493966227-What-derivation-paths-does-Phantom-wallet-support#:~:text=The%20addresses%20are%20grouped%20into,'%2F0'%2F0%2F0.) on matching private keys across Solana, Ethereum, and Polygon.

When exporting, if you export with the `hexadecimal` format, you can easily convert to base58 (Phantom-compatible) with a script like the following:

```javascript theme={"system"}
var web3 = require('@solana/web3.js')
var bs58 = require('bs58')

const uint8arrayToHexString = (buffer) => {
  return [...buffer].map((x) => x.toString(16).padStart(2, "0")).join("");
};

const uint8arrayFromHexString = (hexString) =>
  new Uint8Array(hexString.match(/../g).map((h) => parseInt(h, 16)));

const privateKey = "<your turnkey-provided exported private key (without 0x)>"
const address = "<your solana address>"

const base58DecodedAddress = bs58.decode(address)
const base58DecodedAddressHex = uint8arrayToHexString(base58decodedAddress)
const uintarr = uint8arrayFromHexString(`${privateKey}${base58decodedAddressHex}`)

const imported = web3.Keypair.fromSecretKey(uintarr);
console.log('imported wallet', imported) // verify import

const privateKeyString = bs58.encode(uintarr);

// NOTE: this log is for demonstration purposes only.
// This key material is extremely sensitive and should be handled with care.
console.log('phantom-importable private key string', privateKeyString)
```

# Import Wallet or Private Key
Source: https://docs.turnkey.com/embedded-wallets/code-examples/import

This is a guide to importing your wallet or private key into Turnkey. For more information about the security of this flow, check out [Enclave secure channels](/security/enclave-secure-channels).

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](/sdks/react/using-embedded-wallets#importing-and-exporting-wallets) for the updated packages.

## Implementation guides

Follow along with the Turnkey CLI, Embedded iframe, NodeJS, and Local Storage guides.

### CLI

Install the latest version of Turnkey CLI to access the new import functionality. You can find detailed instructions for installation [here](https://github.com/tkhq/tkcli).

#### Steps

<Steps>
  <Step title="Generate an encryption key">
    ```bash theme={"system"}
    turnkey generate encryption-key \
    --organization $ORGANIZATION_ID \
    --user $USER_ID \
    --encryption-key-name demo-encryption-key
    ```

* The `--user` flag (required) is the id of the user importing the private key; this is required because the underlying encryption keys used for import are scoped to each user.
    * The `--encryption-key-name` flag is to specify a name for the encryption key. Note that an encryption key !== Turnkey API key; an encryption key is used exclusively for secure activities like import and export.
  </Step>

<Step title="Initialize import">
    ```bash theme={"system"}
    turnkey wallets init-import \
    --user $USER_ID \
    --import-bundle-output "./import_bundle.txt" \
    --key-name demo-api-key
    ```

* The `--import-bundle-output` (required) flag is the desired output file path for the “import bundle” that will be received from Turnkey. The “import bundle” contains the ephemeral public key generated by the Turnkey signer enclave for the specified user. The private key plaintext is encrypted to this public key in Step 2.
    * Reminder: The `--key-name` flag specifies the name of API key with which to interact with the Turnkey API service. This should be the name of a previously created key. If you do not have one, visit the quickstart guide for help creating one.
  </Step>

<Step title="Encrypt without saving plaintext to filesystem. This can be done offline:">
    ```bash theme={"system"}
    turnkey encrypt \
    --user $USER_ID \
    --import-bundle-input "./import_bundle.txt" \
    --plaintext-input /dev/fd/3 3<<<"$MNEMONIC_1" \
    --encrypted-bundle-output "./encrypted_bundle.txt" \
    --encryption-key-name demo-encryption-key
    ```

* The `--import-bundle-input` flag (required) is the desired input file path for the “import bundle”.
    * The `--plaintext-input` flag is the desired input file path for the private key plaintext. You can pass a filename here or feed the plaintext string directly into the standard input as shown above.
    * The `--encrypted-bundle-output` (required) flag is the desired output file path for the “encrypted bundle” that will be sent to Turnkey in Step 3. The “encrypted bundle” contains the ephemeral public key generated by the CLI as part of the shared secret computation with the Turnkey signer enclave. It also contains the ciphertext, which is the plaintext input encrypted by the Turnkey signer’s ephemeral public key.
  </Step>

<Step title="Import private key">
    ```bash theme={"system"}
    turnkey wallets import \
    --user $USER_ID \
    --name "demo key"  \
    --encrypted-bundle-input "./encrypted_bundle.txt" \
    --key-name demo-api-key
    ```

* The `--encrypted-bundle-input` (required) flag is the desired input file path for the “encrypted bundle” that will be sent to Turnkey.
    * Options are listed [here](/concepts/wallets) for the `--curve` and `--address-format` flags.
  </Step>
</Steps>

#### Private Key support

Turnkey CLI also supports importing private keys. Follow the same steps as importing a wallet via CLI but use the `turnkey private-keys` commands instead. In Step 2 (`encrypt`), pass a `--key-format` flag for key-specific formatting; the options for private keys are:

* `hexadecimal`: Used for Ethereum. Examples: `0x13eff5b3f9c63eab5d53cff5149f01606b69325496e0e98b53afa938d890cd2e, 13eff5b3f9c63eab5d53cff5149f01606b69325496e0e98b53afa938d890cd2e`
* `solana`: Used for Solana. It’s a base58-encoding of the concatenation of the private key and public key bytes. Example: `2P3qgS5A18gGmZJmYHNxYrDYPyfm6S3dJgs8tPW6ki6i2o4yx7K8r5N8CF7JpEtQiW8mx1kSktpgyDG1xuWNzfsM`

```bash theme={"system"}
turnkey encrypt \
--import-bundle-input "./import_bundle.txt" \
--plaintext-input /dev/fd/3 3<<<"$RAW_KEY_1" \
--key-format “hexadecimal” \
--encrypted-bundle-output "./encrypted_bundle.txt"
```

### Embedded iframe

* We have released open-source code to create target encryption keys and encrypt wallet mnemonics for import. We've deployed a static HTML page hosted on `import.turnkey.com` meant to be embedded as an iframe element (see the code [here](https://github.com/tkhq/frames)). This ensures the mnemonics and keys are encrypted to keys that the user has access to, but that your organization does not (because they live in the iframe, on a separate domain).
* We have also built a package to help you insert this iframe and interact with it in the context of import: [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper)

In the rest of this guide we'll assume you are using these helpers. We also have a [code example](https://github.com/tkhq/sdk/blob/main/examples/wallet-import-export/src/components/ImportWallet.tsx) you can follow along with.

#### Steps

Here's a diagram summarizing the wallet import flow step-by-step ([direct link](/assets/files/wallet_import_steps-6c4753c1e726e1632ce475bc838388c2.png)):

Let's review these steps in detail:

<Steps>
  <Step>
    When a user on your application clicks "import", display a new import UI. We recommend setting this import UI as a new hosted page of your application that contains the iframe element that the user will enter their mnemonic into and an import button.

While the UI is in a loading state, your application uses [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) to insert a new iframe element:

```js theme={"system"}
    const iframeStamper = new IframeStamper({
      iframeUrl: "https://import.turnkey.com",
      // Configure how the iframe element is inserted on the page
      iframeContainer: yourContainer,
      iframeElementId: "turnkey-iframe",
    });

// Inserts the iframe in the DOM.
    await iframeStamper.init();

// Set state to not display iframe
    let displayIframe = "none";

return (
      // The iframe element does not need to be displayed yet
      <div style={{ display: displayIframe }} />
    );
    ```
  </Step>

<Step>
    Your application prompts the user to sign a new `INIT_IMPORT_WALLET` activity with the ID of the user importing the wallet.
  </Step>

<Step>
    Your application polls for the activity response, which contains an import bundle.

Need help setting up async polling? Checkout our guide and helper [here](https://github.com/tkhq/sdk/tree/main/packages/http#withasyncpolling-helper).
  </Step>

<Step>
    Your application injects the import bundle into the iframe and displays the iframe upon success:

```js theme={"system"}
    // Inject import bundle into iframe
    let success = await iframeStamper.injectImportBundle(importBundle);

if (success !== true) {
      throw new Error("unexpected error while injecting import bundle");
    }

// If successfully injected, update the state to display the iframe
    iframeDisplay = "block";
    ```
  </Step>

<Step>
    When a user clicks on the import button on your web page, your application can extract the encrypted mnemonic bundle from the iframe:

```js theme={"system"}
    // Extract the encrypted bundle from the iframe
    let encryptedBundle =
      await iframeStamper.extractWalletEncryptedBundle(importBundle);
    ```

Your applications passes the encrypted bundle as a parameter in a new `IMPORT_WALLET` activity and prompts the user to sign it.

Import is complete!

In your Turnkey dashboard, the imported user Wallet will be flagged as “Imported”.
  </Step>
</Steps>

### NodeJS

A full example Node script can be found here: [https://github.com/tkhq/sdk/tree/main/examples/import-in-node](https://github.com/tkhq/sdk/tree/main/examples/import-in-node)

#### Steps

<Steps>
  <Step title="Initialize a new Turnkey client">
    ```ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-server";
    import {
      encryptPrivateKeyToBundle,
      encryptWalletToBundle,
    } from "@turnkey/crypto";

...

<Step title="Initialize the import process (Turnkey activity)">
    ```ts theme={"system"}
    const initResult = await turnkeyClient.apiClient().initImportWallet({
      userId,
    });
    ```
  </Step>

<Step title="Encrypt wallet to bundle">
    ```ts theme={"system"}
    const walletBundle = await encryptWalletToBundle({
      mnemonic,
      importBundle: initResult.importBundle,
      userId,
      organizationId,
    });
    ```
  </Step>

<Step title="Import wallet (Turnkey activity)">
    ```ts theme={"system"}
    const walletImportResult = await turnkeyClient.apiClient().importWallet({
      userId: userId,
      walletName: "Your imported wallet!",
      encryptedBundle: walletBundle,
      accounts: [], // these are the wallet accounts you'd like to derive; after all, you've just imported a HD wallet! See https://learnmeabitcoin.com/technical/hd-wallets for more
    });
    ```

Congrats! You've imported your wallet 🎉
  </Step>
</Steps>

#### Private Key support

The process for importing a private key instead of wallet is largely similar, but has a key difference in that you must specify the format of your imported private key:

<Steps>
  <Step title="Initialize a new Turnkey client">
    ```js theme={"system"}
    import { Turnkey } from "@turnkey/sdk-server";
    import {
      encryptPrivateKeyToBundle,
      encryptWalletToBundle,
    } from "@turnkey/crypto";

...

<Step title="Initialize the import process (Turnkey activity)">
    ```js theme={"system"}
    const initResult = await turnkeyClient.apiClient().initImportPrivateKey({
      userId,
    });
    ```
  </Step>

<Step title="Encrypt private key to bundle">
    ```js theme={"system"}
    const privateKeyBundle = await encryptPrivateKeyToBundle({
      privateKey,
      keyFormat,
      importBundle: initResult.importBundle,
      userId,
      organizationId,
    });
    ```
  </Step>

<Step title="Import private key (Turnkey activity)">
    ```js theme={"system"}
    const privateKeyImportResult = await turnkeyClient
      .apiClient()
      .importPrivateKey({
        userId: userId,
        privateKeyName: "Your imported private key!",
        encryptedBundle: privateKeyBundle,
        curve: keyFormat == "SOLANA" ? "CURVE_ED25519" : "CURVE_SECP256K1",
        addressFormats:
          keyFormat == "SOLANA"
            ? ["ADDRESS_FORMAT_SOLANA"]
            : ["ADDRESS_FORMAT_ETHEREUM"],
      });
    ```

Congrats! You've imported your private key 🎉
  </Step>
</Steps>

### Local Storage

If you do not have access to an iframe (e.g. in a mobile context) or would prefer not to use an iframe, you can opt to use other environment-agnostic methods to perform import using Turnkey libraries. So while this section is called Local Storage (for consistency with the [Export](/embedded-wallets/code-examples/export) guide), nothing is stored in Local Storage; instead, the relevant `encrypt{Wallet, PrivateKey}ToBundle` method uses an [ephemeral key](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/crypto/src/crypto.ts#L62-L70).

#### Steps

<Steps>
  <Step title="Initialize Turnkey client">
    ```ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";
    import { generateP256KeyPair, encryptWalletToBundle } from "@turnkey/crypto";

...

<Step title="Initialize the import process (Turnkey activity)">
    ```ts theme={"system"}
    const initResult = await passkeyClient.initImportWallet({
      userId, // your user ID
    });
    ```
  </Step>

<Step title="Import wallet (Turnkey activity)">
    ```ts theme={"system"}
    const walletImportResult = await passkeyClient.importWallet({
      userId, // your user ID
      walletName: "Your imported wallet!", // your desired name for the resulting imported wallet
      encryptedBundle: walletBundle,
      accounts: [], // these are the wallet accounts you'd like to derive; after all, you've just imported a HD wallet! See https://learnmeabitcoin.com/technical/hd-wallets for more
    });
    ```

Congrats! You've imported your wallet 🎉

The process for importing a private key instead of wallet is largely similar, but has a key difference in that you must specify the format of your imported private key:
  </Step>
</Steps>

#### Private Key support

<Steps>
  <Step title="Initialize Turnkey client">
    ```ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";
    import { generateP256KeyPair, encryptPrivateKeyToBundle } from "@turnkey/crypto";

...

<Step title="Initialize the import process (Turnkey activity)">
    ```
    const initResult = await passkeyClient.initImportPrivateKey({
      userId, // your user ID
    });
    ```
  </Step>

<Step title="Encrypt private key to bundle">
    ```ts theme={"system"}
    const privateKeyBundle = await encryptPrivateKeyToBundle({
      privateKey, // your private key string
      keyFormat, // your desired key format. See the Private Key notes section for more
      importBundle: initResult.importBundle,
      userId, // your user ID
      organizationId, // your organization ID
    });
    ```
  </Step>

<Step title="Import private key (Turnkey activity)">
    ```ts theme={"system"}
    const privateKeyImportResult = await passkeyClient.importPrivateKey({
      userId,
      privateKeyName: "Your imported private key!", // your desired name for the resulting imported private key
      encryptedBundle: privateKeyBundle,
      curve: keyFormat == "SOLANA" ? "CURVE_ED25519" : "CURVE_SECP256K1",
      addressFormats:
        keyFormat == "SOLANA"
          ? ["ADDRESS_FORMAT_SOLANA"]
          : ["ADDRESS_FORMAT_ETHEREUM"],
    });
    ```

Congrats! You've imported your private key 🎉
  </Step>
</Steps>

## Private Key notes

Turnkey also supports importing Private Keys. Follow the same steps above for importing Wallets as mnemonics, but instead use the `INIT_IMPORT_PRIVATE_KEY` and `IMPORT_PRIVATE_KEY` activities and the `extractKeyEncryptedBundle` method from the [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper). You can pass an optional `keyFormat` to `extractKeyEncryptedBundle(keyFormat)` that will apply either `Hexadecimal` or `Solana` formatting to the private key that is entered in the iframe. The default key format is `hexadecimal`, which is used by MetaMask, MyEtherWallet, Phantom, Ledger, and Trezor for Ethereum keys. For Solana keys, you will need to pass the `solana` key format.

## UI customization

```css theme={"system"}
const iframeCss = `
  iframe {
      box-sizing: border-box;
      width: 400px;
      height: 120px;
      border-radius: 8px;
      border-width: 1px;
      border-style: solid;
      border-color: rgba(216, 219, 227, 1);
      padding: 20px;
  }
`;

return (
  <div style={{ display: iframeDisplay }} id="your-container">
    <style>{iframeCss}</style>
  </div>
);
```

# Sending Sponsored Transactions
Source: https://docs.turnkey.com/embedded-wallets/code-examples/sending-sponsored-transactions

In this guide, we’ll walk through the process of setting up sponsored transactions, with abstractions for transaction construction, broadcast, and gas management, using React.

## SDK Overview

> The SDK primarily abstracts three endpoints: `eth_send_transaction`, `get_send_transaction_status`, and `get_gas_usage`.

You can sign and broadcast transactions in two primary ways:

1. **Using the React handler (`handleSendTransaction`) from `@turnkey/react-wallet-kit`**
   This gives you:
   * modals
   * spinner + chain logo
   * success screen
   * explorer link
   * built-in polling

2. **Using low-level functions in `@turnkey/core`**
   You manually call:
   * `ethSendTransaction` → submit
   * `pollTransactionStatus` → wait for inclusion

3. **Using server-side `@turnkey/sdk-server`**
   This is the right choice for Node.js backends. It exposes the same methods via the server SDK client.

This page walks you through the React flow with full code examples. For using `@turnkey/core` directly, see [Sending Sponsored Transactions](/signing-automation/code-examples/sending-sponsored-transactions).

## Using `handleSendTransaction` (React)

This handler wraps everything: intent creation, signing, Turnkey submission, polling, modal UX, and final success UI.

### Step 1 — Configure the Provider

```ts theme={"system"}
import { TurnkeyProvider } from "@turnkey/react-wallet-kit";

const turnkeyConfig = {
  apiBaseUrl: "https://api.turnkey.com",
  defaultOrganizationId: process.env.NEXT_PUBLIC_TURNKEY_ORG_ID,
  rpId: window.location.hostname,
  iframeUrl: "https://auth.turnkey.com",
};

export default function App({ children }) {
  return (
    <TurnkeyProvider config={turnkeyConfig}>
      {children}
    </TurnkeyProvider>
  );
}
```

***

### Step 2 — Use `handleSendTransaction` inside your UI

```ts theme={"system"}
const { handleSendTransaction, wallets } = useTurnkey();

const walletAccount = wallets[0].accounts[0];

await handleSendTransaction({
  transaction: {
    from: walletAccount.address,
    to: "0xRecipient",
    value: "1000000000000000",
    data: "0x",
    caip2: "eip155:8453",
    sponsor: true,
  },
});
```

* Full React handler implementation [here](https://github.com/tkhq/sdk/blob/e5a153efa90c325d4f5ecfe65d8d2bff8573c64f/packages/react-wallet-kit/src/providers/client/Provider.tsx#L5536)

This automatically:

* opens Turnkey modal
* shows chain logo
* polls until INCLUDED
* displays success page + explorer link

## Checking Gas Usage

You can configure gas limits for both sub-orgs and all orgs. We recommend checking sub-org gas usage against the limit on the client side so your application can handle edge cases when approaching or exceeding the gas limit.

You may also want to monitor your all org gas usage regularly to see if you are approaching your gas limit.

```ts theme={"system"}
const resp = await httpClient?.getGasUsage({})
if (resp?.usageUsd! > resp?.windowLimitUsd!) { // you can also configure this to be a threshold
  console.error("Gas usage limit exceeded for sponsored transactions");
  return
}
```

For additional references leveraging these endpoints, check out our [Swapping Example](https://github.com/tkhq/sdk/tree/main/examples/eth-usdc-swap) and [Sweeping Example](https://github.com/tkhq/sdk/tree/main/examples/sweeper)

## EVM Paymaster Example

You may also leverage our own example for setting up EVM paymaster leveraging the above endpoints. This example shows how to send an erc-20 token on EVM networks using Turnkey's paymaster (gas sponsorship).

Please refer to [with-paymaster](https://github.com/tkhq/sdk/tree/main/examples/with-paymaster) to see how to setup and manage paymaster for your transaction operations.

# Signing Transactions
Source: https://docs.turnkey.com/embedded-wallets/code-examples/signing-transactions

This is a guide to signing transactions in the browser context. While these snippets leverage Ethers, it can be swapped out for other signers in the Viem or Solana contexts. See [here](https://github.com/tkhq/sdk/tree/main/examples/with-eth-passkeys-galore) for an example with both Ethers and Viem in the passkey + browser context, and [here](https://github.com/tkhq/sdk/tree/main/examples/with-solana-passkeys) for a similar example with Solana.

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](/sdks/react/signing) for the updated packages.

## Steps using `@turnkey/sdk-react`

This process is made the most seamless by leveraging our [React package](/sdks/react). Read on for a non-React implementation.

<Steps>
  <Step title="Initialize the React Provider">
    ```js theme={"system"}
    import { TurnkeyProvider } from "@turnkey/sdk-react";
    const turnkeyConfig = {
      apiBaseUrl: "https://api.turnkey.com",
      defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID, // prefix with NEXT_PUBLIC for NextJS
      rpId: process.env.RPID, // your application's domain
      iframeUrl: "https://auth.turnkey.com"
    }

...

<Step title="Initialize an Ethers Provider and Turnkey Signer using the Passkey Client">
    ```js theme={"system"}
    import { ethers } from "ethers";
    import { TurnkeySigner } from "@turnkey/ethers";

import { useTurnkey } from "@turnkey/sdk-react";
    const { turnkey, passkeyClient } = useTurnkey();

const provider = new ethers.JsonRpcProvider(<provider api url>);
    const currentUser = await turnkey.getCurrentUser();
    const turnkeySigner = new TurnkeySigner({
      client: passkeyClient,
      organizationId: currentUser.organization.organizationId,
      signWith: "<wallet address to sign with>"
    })
    const connectedSigner = turnkeySigner.connect(provider);
    ```
  </Step>

<Step title="Call `sendTransaction` with the Turnkey Signer">
    ```js theme={"system"}
    const transactionRequest = {
      to: "<destination address>",
      value: ethers.parseEther("<amount to send>"),
      type: 2,
    };
    const sendTransaction = await connectedSigner.sendTransaction(transactionRequest);
    ```
  </Step>
</Steps>

## Alternative Steps (non-React)

<Steps>
  <Step title="Initialize the Passkey Client">
    ```js theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";

<Step title="Initialize an Ethers Provider and Turnkey Signer">
    ```
    import { ethers } from "ethers";
    import { TurnkeySigner } from "@turnkey/ethers";

const provider = new ethers.JsonRpcProvider(<provider api url>);
    const currentUser = await turnkey.getCurrentUser(); // assumes user details have been stored in LocalStorage via `login()`
    const turnkeySigner = new TurnkeySigner({
      client: passkeyClient,
      organizationId: currentUser.organization.organizationId,
      signWith: "<wallet address to sign with>"
    })
    const connectedSigner = turnkeySigner.connect(provider);
    ```
  </Step>

<Step title="Call sendTransaction with the Turnkey Signer">
    ```js theme={"system"}
    const transactionRequest = {
      to: "<destination address>",
      value: ethers.parseEther("<amount to send>"),
      type: 2,
    };
    const sendTransaction =
      await connectedSigner.sendTransaction(transactionRequest);
    ```
  </Step>
</Steps>

# Wallet Authentication
Source: https://docs.turnkey.com/embedded-wallets/code-examples/wallet-auth

In this guide, we'll explore how to leverage the `WalletClient` in the Turnkey SDK to authenticate requests to Turnkey's API using either Solana or Ethereum wallets.

> ⚠️ **This example is outdated !**<br />
> Head over to [SDK Reference](/sdks/react/using-external-wallets/overview) for the updated packages.

## Initialize

Begin by initializing the Turnkey SDK by passing in a config object containing:

* `apiBaseUrl`: The base URL of the Turnkey API: `https://api.turnkey.com`.
* `defaultOrganizationId`: Your parent organization ID, which you can find in the [Turnkey dashboard](https://app.turnkey.com/dashboard).
* `wallet`: The wallet interface used to sign requests. In this example, we'll use the `EthereumWallet` interface.

```ts config.ts theme={"system"}
import { EthereumWallet } from '@turnkey/wallet-stamper';

export const turnkeyConfig = {
  // Turnkey API base URL
  apiBaseUrl: 'https://api.turnkey.com',
  // Your parent organization ID
  defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
  // The wallet interface used to sign requests
  wallet: new EthereumWallet(),
};
```

First, wrap your application with the `TurnkeyProvider` in your `app/layout.tsx` file.
As this file is required by Next.js to be a server component, we need to define a `TurnkeyClientProvider` client component.

```tsx app/TurnkeyClientProvider.tsx theme={"system"}
'use client';

import { TurnkeyProvider } from '@turnkey/sdk-react';

import { turnkeyConfig } from './config';

export function TurnkeyClientProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>;
}
```

```tsx app/layout.tsx theme={"system"}
import './globals.css';
import '@turnkey/sdk-react/styles';

import { TurnkeyClientProvider } from './TurnkeyClientProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <TurnkeyClientProvider>{children}</TurnkeyClientProvider>
      </body>
    </html>
  );
}
```

Then, create a new page component `app/page.tsx` where we'll implement the wallet authentication functionality:

<Tabs>
  <Tab title="Next.js">
    ```tsx app/page.tsx theme={"system"}
    "use client";

import { useState } from "react";
    import { useTurnkey } from "@turnkey/sdk-react";

export default function WalletAuth() {
      const { walletClient } = useTurnkey();

// We'll add more functionality here in the following steps

return <div>{/* We'll add UI elements here */}</div>;
    }

```
  </Tab>

<Tab title="TypeScript">
    Create a new file `src/wallet-auth.ts` where we'll implement the wallet authentication functionality:

```ts src/wallet-auth.ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-browser";
    import { EthereumWallet } from "@turnkey/wallet-stamper";
    import { turnkeyConfig } from "./config";

// Initialize the Turnkey SDK with the config object defined above
    const turnkey = new Turnkey(turnkeyConfig);

// Initialize the Wallet Client with the EthereumWallet interface
    const walletClient = turnkey.walletClient(new EthereumWallet());

// We'll add more functionality here in the following steps
    ```
  </Tab>
</Tabs>

## Sign Up

In this section, we'll guide you through the process of implementing a sign-up flow using an Ethereum wallet for authentication. The sign-up process involves creating a new sub-organization within your existing organization. This requires authentication of the parent organization using its public/private key pair. Additionally, we'll cover how to verify if a user already has an associated sub-organization before proceeding.

### Server-side

Initialize the Turnkey SDK on the **server-side** using the `@turnkey/sdk-server` package. This setup enables you to authenticate requests to Turnkey's API using the parent organization's public/private API key pair. This is required to create new sub-organizations on behalf of a user.

```tsx app/actions.ts theme={"system"}
    'use server';

import { Turnkey } from '@turnkey/sdk-server';
    import { turnkeyConfig } from './config';

const { apiBaseUrl, defaultOrganizationId } = turnkeyConfig;

// Initialize the Turnkey Server Client on the server-side
    const turnkeyServer = new Turnkey({
      apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY!,
      apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY!,
      apiBaseUrl,
      defaultOrganizationId,
    }).apiClient();
    ```
  </Tab>

<Tab title="TypeScript">
    ```ts src/wallet-auth-server.ts theme={"system"}
    import { Turnkey } from "@turnkey/sdk-server";
    import { turnkeyConfig } from "./config";

const { apiBaseUrl, defaultOrganizationId } = turnkeyConfig;

// Initialize the Turnkey Server Client on the server-side
    const turnkeyServer = new Turnkey({
    apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY,
    apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY,
    apiBaseUrl,
    defaultOrganizationId,
    }).apiClient();

```
  </Tab>
</Tabs>

### Check for Existing User

Before signing up a new user, we can try and retrieve the user's sub-organization ID using the public key associated with the Ethereum or Solana account they want to authenticate with. If a sub-organization is found, we can proceed with authentication; otherwise, we assume the user is signing up.

We'll use the `getPublicKey` method on the `WalletClient` instance which will retrieve the public key from the user's wallet.

<Info>
  The main distinction between signing with an Ethereum Wallet and a Solana Wallet lies in how the public key is obtained. For Solana, the public key can be directly derived from the wallet. In contrast, with Ethereum, the secp256k1 public key isn't directly accessible. Instead, you need to first obtain a signature from the user and then recover the public key from that signature. This requires an additional step of signing a message with the user's Ethereum wallet before we can retrieve the public key.
</Info>

We'll define this function in the server-side code we initialized earlier.

<Tabs>
  <Tab title="Next.js">
    ```ts app/actions.ts theme={"system"}
    "use server";

// ...

export const getSubOrg = async (publicKey: string) => {
      try {
        const { organizationIds } = await turnkeyServer.getSubOrgIds({
          organizationId: turnkeyConfig.defaultOrganizationId,
          filterType: "PUBLIC_KEY",
          filterValue: publicKey,
        });

return organizationIds[0] ?? null;
      } catch (err: any) {
          return null;
      }
    };
    ```
  </Tab>

<Tab title="TypeScript">
    ```ts src/wallet-auth-server.ts theme={"system"}
    'use server';

// ...

export const getSubOrg = async (publicKey: string) => {
      try {
        const { organizationIds } = await turnkeyServer.getSubOrgIds({
          organizationId: turnkeyConfig.defaultOrganizationId,
          filterType: 'PUBLIC_KEY',
          filterValue: publicKey,
        });

return organizationIds[0] ?? null;
      } catch (err: any) {
        return null;
      }
    };
    ```
  </Tab>
</Tabs>

Next, we'll add the client-side functionality to the `app/page.tsx` file we created earlier importing the `getSubOrg` function we defined in our server action. We'll use the `getSubOrg` function in the login method to check if a user already has a sub-organization.

<Tabs>
  <Tab title="Next.js">
    ```tsx app/page.tsx theme={"system"}
    'use client';

import { useState } from 'react';
    import { useTurnkey } from '@turnkey/sdk-react';
    // Import the getSubOrg function we defined earlier
    import { getSubOrg } from './actions';

export default function WalletAuth() {
      const { walletClient } = useTurnkey();

const login = async () => {
    // Get the public key of the wallet, for Ethereum wallets this will trigger a prompt for the user to sign a message
    const publicKey = await walletClient?.getPublicKey();

if (!publicKey) {
          throw new Error('No public key found');
        }

const subOrgId = await getSubOrg(publicKey);
        if (!subOrgId) {
          // User does not have a sub-organization, proceed with sign-up
        }
        // User has a sub-organization, proceed with login

};

return (
    <div>
    <button onClick={login}>Sign In</button>
    </div>
    );
    }

```
  </Tab>

<Tab title="TypeScript">
    ```ts src/wallet-auth.ts theme={"system"}
    import { getSubOrg } from './wallet-auth-server';
    // ...
    const walletClient = turnkey.walletClient(new EthereumWallet());

export const login = async () => {
      // Get the public key of the wallet, for Ethereum wallets this will trigger a prompt for the user to sign a message
      const publicKey = await walletClient?.getPublicKey();

if (!publicKey) {
        throw new Error('No public key found');
      }

const subOrgId = await getSubOrg(publicKey);
      if (!subOrgId) {
        // User does not have a sub-organization, proceed with sign-up
      }
      // User has a sub-organization, proceed with login
    };
    ```
  </Tab>
</Tabs>

### Create Sub-Organization

Next, we'll define a method to create a sub-organization for new user sign-ups.

For more information, refer to the [Sub-Organizations](/concepts/sub-organizations) guide.

<Tabs>
  <Tab title="Next.js">
    We'll define another server action `createSubOrg` to create a sub-organization for new user sign-ups.

```ts app/actions.ts theme={"system"}
    'use server';

// ...

// Import the default Ethereum accounts helper
    import { DEFAULT_ETHEREUM_ACCOUNTS } from '@turnkey/sdk-browser';

export const createSubOrg = async (
      publicKey: string,
      curveType: 'API_KEY_CURVE_ED25519' | 'API_KEY_CURVE_SECP256K1'
    ) => {
      const apiKeys = [
        {
          apiKeyName: `Wallet Auth - ${publicKey}`,
          // The public key of the wallet that will be added as an API key and used to stamp future requests
          publicKey,
          // We set the curve type to 'API_KEY_CURVE_ED25519' for solana wallets
          // If using an Ethereum wallet, set the curve type to 'API_KEY_CURVE_SECP256K1'
          curveType,
        },
      ];

const subOrg = await turnkeyServer.createSubOrganization({
        // The parent organization ID
        organizationId: turnkeyConfig.defaultOrganizationId,
        subOrganizationName: 'New Sub Org',
        rootUsers: [
          {
            // Replace with user provided values if desired
            userName: 'New User',
            userEmail: 'wallet@domain.com',
            apiKeys,
            authenticators: [],
            oauthProviders: [],
          },
        ],
        rootQuorumThreshold: 1,
        wallet: {
          walletName: 'Default Wallet',
          // This is used to create a new Ethereum wallet for the sub-organization
          accounts: DEFAULT_ETHEREUM_ACCOUNTS,
        },
      });

return subOrg;
    };
    ```

Then, we'll import and use this `createSubOrg` function within the login method. The curve type is set to `API_KEY_CURVE_SECP256K1` since we're using an Ethereum wallet in this example.

```tsx app/page.tsx theme={"system"}
    'use client';
    import { getSubOrg, createSubOrg } from './actions';
    // ...

export default function WalletAuth() {
      const { walletClient } = useTurnkey();

const login = async () => {
        // Get the public key of the wallet, for Ethereum wallets this will trigger a prompt for the user to sign a message
        const publicKey = await walletClient?.getPublicKey();

if (!publicKey) {
          throw new Error('No public key found');
        }

const subOrgId = await getSubOrg(publicKey);
        if (!subOrgId) {
          const subOrgResponse = await createSubOrg(
            publicKey,
            'API_KEY_CURVE_SECP256K1'
          );
          const subOrg = subOrgResponse?.subOrganizationId ?? null;

if (!subOrg) throw new Error('Failed to create sub-organization');
        }
        // In the next step we'll sign in the user
      };

return (
        <div>
          <button onClick={login}>Sign In</button>
        </div>
      );
    }
    ```
  </Tab>

<Tab title="TypeScript">
    We'll define another server-side function `createSubOrg`, to create a sub-organization for new user sign-ups.

```ts src/wallet-auth-server.ts theme={"system"}
    // ...

// Import the default Ethereum accounts helper
    import { DEFAULT_ETHEREUM_ACCOUNTS } from '@turnkey/sdk-browser';

return subOrg;
    };
    ```

Then, we'll import and use this `createSubOrg` function within the login method. The curve type is set to `API_KEY_CURVE_SECP256K1` since we're using an Ethereum wallet in this example.

```ts src/wallet-auth.ts theme={"system"}
    import { getSubOrg, createSubOrg } from './wallet-auth-server';
    // ...
    const walletClient = turnkey.walletClient(new EthereumWallet());

if (!publicKey) {
        throw new Error('No public key found');
      }

const subOrgId = await getSubOrg(publicKey);
      if (!subOrgId) {
        const subOrgResponse = await createSubOrg(
          publicKey,
          'API_KEY_CURVE_SECP256K1'
        );
        const subOrg = subOrgResponse?.subOrganizationId ?? null;

if (!subOrg) throw new Error('Failed to create sub-organization');
      }
      // In the next step we'll sign in the user
    };
    ```
  </Tab>
</Tabs>

## Sign In

At this point, we have a working sign-up flow. Next, we'll implement the signing in functionality by creating a read-write session, retrieving the user's wallets and adding a new one.

Create a read-write session for the user by calling the `loginWithWallet` method on the `WalletClient` instance which will use a newly generated `indexedDb` API key. This will save a read-write session token to the `localStorage` to authenticate future read-write requests.

<Tabs>
  <Tab title="Next.js">
    ```tsx app/page.tsx theme={"system"}
    'use client';

import { useState } from 'react';
    import { useTurnkey } from '@turnkey/sdk-react';
    import { getSubOrg, createSubOrg } from './actions';
    import { SessionType } from '@turnkey/sdk-types';
    import { DEFAULT_ETHEREUM_ACCOUNTS } from '@turnkey/sdk-browser';

export default function WalletAuth() {
      const [wallets, setWallets] = useState<any[]>([]);
      const [session, setSession] = useState<any | null>(null);
      const { walletClient, indexedDbClient, turnkey } = useTurnkey();

const login = async () => {
        try {
          // Get the public key of the wallet, for Ethereum wallets this will trigger a prompt for the user to sign a message
          const publicKey = await walletClient?.getPublicKey();
          if (!publicKey) throw new Error('No public key found');

if (!walletClient) {
            throw new Error('Wallet client not initialized');
          }

const subOrgId = await getSubOrg(publicKey);

if (!subOrgId) {
            const subOrgResponse = await createSubOrg(
              publicKey,
              'API_KEY_CURVE_SECP256K1'
            );
            const subOrg = subOrgResponse?.subOrganizationId ?? null;

if (!subOrg) throw new Error('Failed to create sub-organization');
            console.log('Sub-Organization created:', subOrg);
          }

if (!indexedDbClient) throw new Error('IndexedDb client not available');

// Reset the indexedDb key pair and session before each login
          // Note that session reset is important when switching between multiple wallets within the same browser
          await turnkey?.logout();
          await client?.clear();
          await indexedDbClient.resetKeyPair();
          const pubKey = await indexedDbClient.getPublicKey();

await walletClient!.loginWithWallet({
            sessionType: SessionType.READ_WRITE, // use SessionType.READ_ONLY for read-only sessions
            publicKey: pubKey!,
          });

console.log('Login successful');

const session = await turnkey?.getSession();
          setSession(session);

const subOrganizationId = session!.organizationId;

// get existing suborg wallets
          const wallets = await indexedDbClient.getWallets({
            organizationId: subOrgId!,
          });
          setWallets(wallets.wallets);

// create a new wallet with an Ethereum wallet account
          const newWalletResponse = await indexedDbClient.createWallet({
            walletName: 'New Wallet 1',
            accounts: DEFAULT_ETHEREUM_ACCOUNTS,
          });
          console.log('Created new wallet:', newWalletResponse);

const updatedWallets = await indexedDbClient.getWallets({
            organizationId: subOrganizationId,
          });

setWallets(updatedWallets.wallets);
        } catch (err) {
          console.error('Login error:', err);
        }
      };

return (
        <div className="max-w-md mx-auto bg-white rounded-lg shadow-md p-6">
            <h2 className="text-xl font-bold mb-4 text-gray-800">
              Turnkey Wallet Auth
            </h2>

{/* If logged in: Show wallets */}
            {session && wallets.length > 0 && (
              <div className="space-y-4 mb-6">
                <h3 className="text-lg font-semibold text-gray-700">🧾 Wallets</h3>
                {wallets.map((wallet) => (
                  <div
                    key={wallet.walletId}
                    className="border border-gray-200 rounded-md p-3 bg-gray-50 text-sm"
                  >
                    <div className="font-medium text-gray-800">
                      {wallet.walletName}
                    </div>
                    <div className="text-gray-500 text-xs">
                      Wallet ID: {wallet.walletId}
                    </div>
                  </div>
                ))}
              </div>
            )}

{/* If not logged in: Show Sign In */}
            {walletClient && !session && (
              <button
                onClick={login}
                className="w-full sm:w-auto bg-gray-700 hover:bg-gray-800 text-white font-semibold py-2 px-4 rounded-md transition"
              >
                Sign In
              </button>
            )}
          </div>
        </div>
      );
    }
    ```
  </Tab>

<Tab title="TypeScript">
    ```ts src/wallet-auth.ts theme={"system"}
    import { Turnkey } from '@turnkey/sdk-browser';
    import { EthereumWallet } from '@turnkey/wallet-stamper';
    import { turnkeyConfig } from './config';
    import { getSubOrg, createSubOrg } from './wallet-auth-server';
    import { SessionType } from '@turnkey/sdk-types';
    import { DEFAULT_ETHEREUM_ACCOUNTS } from '@turnkey/sdk-browser';

// Initialize the Turnkey SDK with the config object defined above
    const turnkey = new Turnkey(turnkeyConfig);

// Initialize the Wallet Client with the EthereumWallet interface
    const walletClient = turnkey.walletClient(new EthereumWallet());

export const login = async () => {
      try {
        // Get the public key of the wallet, for Ethereum wallets this will trigger a prompt for the user to sign a message
        const publicKey = await walletClient?.getPublicKey();

if (!publicKey) {
          throw new Error('No public key found');
        }

if (!walletClient) {
          throw new Error('Wallet client not initialized');
        }

if (!subOrg) throw new Error('Failed to create sub-organization');
          console.log('Sub-Organization created:', subOrg);
        }

// Initialize the indexedDbClient
        const client = await turnkey.indexedDbClient();

if (!client) {
          throw new Error('indexedDbClient not initialized');
        }

// Reset the indexedDb key pair and session before each login
        // Note that session reset is important when switching between multiple wallets within the same browser
        await turnkey?.logout();
        await client?.clear();
        await client!.resetKeyPair();
        const pubKey = await client!.getPublicKey();

await walletClient!.loginWithWallet({
          sessionType: SessionType.READ_WRITE, // use SessionType.READ_ONLY for read-only sessions
          publicKey: pubKey!,
        });

console.log('Login successful');

const session = await turnkey?.getSession();

const subOrganizationId = session!.organizationId;

// get existing suborg wallets
        const wallets = await client.getWallets({
          organizationId: subOrgId!,
        });

// create a new wallet with an Ethereum wallet account
        const newWalletResponse = await client.createWallet({
          walletName: 'New Wallet 1',
          accounts: DEFAULT_ETHEREUM_ACCOUNTS,
        });
        console.log('Created new wallet:', newWalletResponse);

const updatedWallets = await client.getWallets({
          organizationId: subOrganizationId,
        });
      } catch (err) {
        console.error('Login error:', err);
      }
    };
    ```
  </Tab>
</Tabs>

## Sign in with a Solana wallet

As with Solana wallets there's not standard API like `personal_sign` for Ethereum, we'll need to build a couple of things:

* Use the Turnkey `SolanaWalletInterface` to build our own `SolanaWallet()` function that would get the public key and sign a message. Create this new `SolanaWalletFactory.ts` component:

```tsx app/SolanaWalletFactory.ts theme={"system"}
// This wrapper implements SolanaWalletInterface for WalletStamper
import { WalletType, SolanaWalletInterface } from "@turnkey/wallet-stamper";

export function SolanaWallet(wallet: {
  publicKey: { toBytes(): Uint8Array } | null;
  signMessage?: (msg: Uint8Array) => Promise<Uint8Array>;
}): SolanaWalletInterface {
  return {
    type: WalletType.Solana,

async getPublicKey() {
      if (!wallet.publicKey) throw new Error("No public key");
      return Buffer.from(wallet.publicKey.toBytes()).toString("hex");
    },

async signMessage(message: string) {
      if (!wallet.signMessage) {
        throw new Error("Wallet does not support signMessage");
      }
      const encoded = new TextEncoder().encode(message);
      const signature = await wallet.signMessage(encoded);
      return Buffer.from(signature).toString("hex");
    },
  };
}
```

* Use the Solana wallet-addapter to detect and connect the installed wallets. Create this SolanaWalletProvider.tsx component:

```tsx app/SolanaWalletProvider.tsx theme={"system"}
"use client";

import { FC, ReactNode } from "react";
import { ConnectionProvider, WalletProvider } from "@solana/wallet-adapter-react";
import { WalletModalProvider } from "@solana/wallet-adapter-react-ui";
import { WalletAdapterNetwork } from "@solana/wallet-adapter-base";

export const SolanaWalletContextProvider: FC<{ children: ReactNode }> = ({ children }) => {
  const network = WalletAdapterNetwork.Mainnet;

const endpoint = "https://api.mainnet-beta.solana.com";

return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={[]} autoConnect> // you can add adapters for walllets not auto-detected here
        <WalletModalProvider>{children}</WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  );
};
```

Update the layout.tsx file:

```tsx app/layout.tsx theme={"system"}
import "./globals.css";
import "@solana/wallet-adapter-react-ui/styles.css";
import { SolanaWalletContextProvider } from "./SolanaWalletProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SolanaWalletContextProvider>
          {children}
        </SolanaWalletContextProvider>
      </body>
    </html>
  );
}
```

Update the config.ts file to include Solana:

```ts config.ts theme={"system"}
import { EthereumWallet } from "@turnkey/wallet-stamper";
import { SolanaWallet } from "./SolanaWalletFactory";

export const turnkeyConfig = {
  apiBaseUrl: "https://api.turnkey.com",
  defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
};

export const turnkeyEthereumConfig = {
  ...turnkeyConfig,
  wallet: new EthereumWallet(),
};

// Factory function for Solana
export function createSolanaConfig(wallet: Parameters<typeof SolanaWallet>[0]) {
  return {
    ...turnkeyConfig,
    wallet: SolanaWallet(wallet),
  };
}
```

Now let's put everything together:

```tsx app/page.tsx expandable theme={"system"}
'use client';

import { useWallet } from '@solana/wallet-adapter-react';
import { WalletMultiButton } from '@solana/wallet-adapter-react-ui';
import { Turnkey } from '@turnkey/sdk-browser';
import { getSubOrg, createSubOrg } from './actions';
import { useCallback, useEffect, useState } from 'react';
import { DEFAULT_ETHEREUM_ACCOUNTS } from '@turnkey/sdk-browser';
import { SessionType } from '@turnkey/sdk-types';
import { SolanaWallet } from "./SolanaWalletFactory";
import { createSolanaConfig } from "./config";

export default function WalletAuth() {
  const wallet = useWallet();
  const [mounted, setMounted] = useState(false);
  const [session, setSession] = useState<any | null>(null);
  const [wallets, setWallets] = useState<any[]>([]);

useEffect(() => {
    setMounted(true);
  }, []);

const login = useCallback(async () => {
    try {
      if (!wallet.connected || !wallet.publicKey) {
        throw new Error('Wallet not connected');
      }
      
      const turnkeyConfig = createSolanaConfig(wallet);
      const turnkey = new Turnkey(turnkeyConfig);
      const walletClient = turnkey.walletClient(SolanaWallet(wallet));

// Get the injected wallet public key
      const publicKey = await walletClient?.getPublicKey();

const subOrgId = await getSubOrg(publicKey);
      if (!subOrgId) {
        const subOrgResponse = await createSubOrg(
          publicKey,
          'API_KEY_CURVE_ED25519'
        );
        const subOrg = subOrgResponse?.subOrganizationId ?? null;

if (!subOrg) throw new Error('Failed to create sub-organization');
        console.log('Sub-Organization created:', subOrg);
      }

// Initialize the indexedDbClient
      const client = await turnkey.indexedDbClient();

if (!client) {
        throw new Error('indexedDbClient not initialized');
      }

// Reset the indexedDb key pair and session before each login
      // Note that session reset is important when switching between multiple wallets within the same browser
      await turnkey?.logout();
      await client?.clear();
      await client!.resetKeyPair();
      
      // Get the indexedDbClient public key
      const pubKey = await client!.getPublicKey();

await walletClient!.loginWithWallet({
        sessionType: SessionType.READ_WRITE, // use SessionType.READ_ONLY for read-only sessions
        publicKey: pubKey!,
      });

console.log('Login successful');

const session = await turnkey?.getSession();
      setSession(session);

const subOrganizationId = session!.organizationId;

// Get existing suborg wallets
      const wallets = await client.getWallets({
        organizationId: subOrgId!,
      });
      setWallets(wallets.wallets);

// Create a new wallet with an Ethereum wallet account
      const newWalletResponse = await client.createWallet({
        walletName: 'New Wallet 1',
        accounts: DEFAULT_ETHEREUM_ACCOUNTS,
      });

const updatedWallets = await client.getWallets({
        organizationId: subOrganizationId,
      });
      setWallets(updatedWallets.wallets);
    } catch (err) {
      console.error('Login error:', err);
    }
  }, [wallet]);

if (!mounted) return null;

return (
    <div className="max-w-md mx-auto bg-white rounded-lg shadow-md p-6 space-y-4">
      <h2 className="text-xl font-bold mb-4 text-gray-800">
        Turnkey Solana Wallet Auth
      </h2>

{session && wallets.length > 0 && (
        <div className="space-y-4 mb-6">
          <h3 className="text-lg font-semibold text-gray-700">🧾 Wallets</h3>
          {wallets.map((wallet) => (
            <div
              key={wallet.walletId}
              className="border border-gray-200 rounded-md p-3 bg-gray-50 text-sm"
            >
              <div className="font-medium text-gray-800">
                {wallet.walletName}
              </div>
              <div className="text-gray-500 text-xs">
                Wallet ID: {wallet.walletId}
              </div>
            </div>
          ))}
        </div>
      )}

{!session && (
        <>
          {!wallet.connected && <WalletMultiButton />}

{wallet.connected && (
            <div className="flex flex-wrap gap-2">
              <button
                onClick={login}
                className="bg-purple-700 hover:bg-purple-800 text-white font-semibold py-2 px-4 rounded-md transition"
              >
                Sign In
              </button>
              <WalletMultiButton />
            </div>
          )}
        </>
      )}
    </div>
  );
}
```

## Examples

You can find examples of how to implement the above functionality using the indexedDbClient and more in the following repositories:

# Features
Source: https://docs.turnkey.com/embedded-wallets/features/overview

# Overview
Source: https://docs.turnkey.com/embedded-wallets/overview

With Embedded Wallets, you can create custom wallet experiences that are seamlessly integrated into your product, without compromising on security. Whether you need custodial or non-custodial wallets, our infrastructure provides the foundation for building innovative, user-friendly crypto products.

### Why Embedded Wallets?

Embedded Wallets give you the freedom to design and control the entire user experience, while offloading the complexity and risk of private key management to Turnkey.

With Embedded Wallets, you can:

* Leverage pre-built UI components to speed up your integration
* Easily create a variety of wallets for your users
* Authenticate users via email, phone number, biometrics, social logins, etc
* Determine delegated access and co-owernership controls
* Access out-of-the-box support for multiple chains and assets
* Sign multiple transactions without additional approvals
* Access simple integrations for gas sponsorship and smart contract wallets

### Custodial vs non-custodial

Turnkey's Embedded Wallets are built on top of Sub-Organizations.
Each wallet is represented by a sub-organization, which can be configured with different security settings and access controls.

* For custodial wallets, your application holds the master key and can initiate transactions on behalf of users.
* For non-custodial wallets, users hold their own private keys and must approve each transaction,
  using one of their configured [authentication](/authentication/overview) methods.

Below, we'll dive into how we set each of these up but first, let's make sure you're familiar with
the Embedded Wallets concepts and architecture.

### Embedded Wallets Quickstart

Head over to the [Getting Started](/sdks/react/getting-started) guide to set up your React app with `@turnkey/react-wallet-kit`.

Looking for more support? Check out our Demos, SDKs and Code Examples below!

## Demos

### Demo Embedded Wallet ([code](https://github.com/tkhq/demo-embedded-wallet))

A comprehensive demo showcasing how to build an embedded wallet using Turnkey. This demo uses the [`@turnkey/sdk-browser`](https://www.npmjs.com/package/@turnkey/sdk-browser), [`@turnkey/sdk-react`](https://www.npmjs.com/package/@turnkey/sdk-react) and [`@turnkey/sdk-server`](https://www.npmjs.com/package/@turnkey/sdk-server) packages and includes features such as:

* User authentication with passkeys, email auth, and OAuth
* Creating new wallets and wallet accounts
* Sending and receiving funds
* Importing/Exporting a wallet
* Adding a credential to the wallet

See [https://github.com/tkhq/demo-embedded-wallet](https://github.com/tkhq/demo-embedded-wallet) for the code.

### Demo Consumer Wallet ([code](https://github.com/tkhq/demo-consumer-wallet))

A minimal consumer wallet app powered by Turnkey. Behind the scenes, it uses [`@turnkey/ethers`](https://www.npmjs.com/package/@turnkey/ethers) for signing and WalletConnect (v1) for accessing dapps.

See [https://github.com/tkhq/demo-consumer-wallet](https://github.com/tkhq/demo-consumer-wallet) for the code.

### Demo Embedded Wallet ([code](https://github.com/tkhq/demo-embedded-wallet), [live link](https://wallet.tx.xyz))

A wallet application showing how users can register and authenticate using passkeys. This demo uses the Turnkey API to create a new [Turnkey Sub-Organization](/concepts/sub-organizations) for each user, create a testnet Ethereum address and send a transaction on Sepolia (ETH testnet).

See [https://wallet.tx.xyz](https://wallet.tx.xyz) (and [https://github.com/tkhq/demo-embedded-wallet](https://github.com/tkhq/demo-embedded-wallet) for the code).

### Demo Ethers Passkeys ([code](https://github.com/tkhq/demo-ethers-passkeys))

A simple application demonstrating how to create sub-organizations, create private keys, and sign with the [`@turnkey/ethers`](https://github.com/tkhq/sdk/tree/main/packages/ethers) signer, using passkeys.

See [https://github.com/tkhq/demo-ethers-passkeys](https://github.com/tkhq/demo-ethers-passkeys) for the code.

### Demo Viem Passkeys ([code](https://github.com/tkhq/demo-viem-passkeys))

A similar, simple application demonstrating how to create sub-organizations, create private keys, and sign with the [`@turnkey/viem`](https://github.com/tkhq/sdk/tree/main/packages/viem) signer, using passkeys.

See [https://github.com/tkhq/demo-viem-passkeys](https://github.com/tkhq/demo-viem-passkeys) for the code.

### Demo Viem Passkeys with Gelato Relay ([code](https://github.com/gelatodigital/gelato-turnkey-passkeys-relay))

This example demonstrates how to leverage Turnkey’s secure key management and Gelato's battle-tested relay infrastructure to enable seamless, sponsored interactions with meta-transactions using the [`@turnkey/viem`](https://github.com/tkhq/sdk/tree/main/packages/viem) signer and [`@gelatonetwork/relay-sdk-viem`](https://github.com/gelatodigital/relay-sdk-viem).

#### How Infinex Leverages Turnkey and Gelato

Infinex, a platform designed to unify the decentralized ecosystem and applications under a single UX layer, eliminates the complexities of navigating fragmented crypto protocols. By integrating **Turnkey** and **Gelato**, Infinex delivers a seamless, secure, and cost-efficient experience for decentralized finance users.

* **Gasless Transactions with Gelato**: Leveraging Gelato’s Relay (ERC-2771), Infinex enables fully **sponsored transactions**, allowing users to interact with decentralized applications without ever paying gas fees. This enhances accessibility and usability, ensuring that users can participate without holding or managing native blockchain tokens for fees.

The synergy between Turnkey and Gelato allows Infinex to offer an intuitive, cost-free user experience while maintaining the highest standards of security and scalability.

### React Native Demo App ([code](https://github.com/tkhq/react-native-demo-wallet))

A React Native app that demonstrates how to use the Turnkey's JavaScript packages in a mobile environment to authenticate users, create wallets, export wallets, sign messages, and more

See [https://github.com/tkhq/react-native-demo-wallet](https://github.com/tkhq/react-native-demo-wallet)
for the code.

### Flutter Demo App ([code](https://github.com/tkhq/dart-sdk/tree/main/examples/flutter-demo-app))

A Flutter app that demonstrates how to use the Turnkey's Flutter packages to authenticate users, create wallets, export wallets, sign messages, and more

See [https://github.com/tkhq/dart-sdk/tree/main/examples/flutter-demo-app](https://github.com/tkhq/dart-sdk/tree/main/examples/flutter-demo-app)
for the code

### SDKs

<div>
  <SquareCard icon={<Logo id="react" className="h-8 w-8" />} label="React" href="/sdks/react" />

<SquareCard icon={<Logo id="react-native" className="h-8 w-8" />} label="React Native" href="/sdks/react-native" />

<SquareCard icon={<Logo id="ios-swift" className="h-8 w-8" />} label="iOS (Swift)" href="/sdks/swift" />

<SquareCard icon={<Logo id="flutter" className="h-8 w-8" />} label="Flutter" href="/sdks/flutter" />

<SquareCard icon={<Logo id="typescript" className="h-8 w-8" />} label="Typescript" href="/sdks/javascript-browser" />

<SquareCard icon={<Logo id="kotlin" className="h-8 w-8" />} label="Kotlin" href="/sdks/kotlin" />
</div>

### Next Steps

Learn more about our powerful features [here](/embedded-wallets/features/overview).

# FAQ
Source: https://docs.turnkey.com/faq

## Authentication and credentials

<AccordionGroup>
  <Accordion title="Can I sign up for Turnkey multiple times with the same email?">
    When you authenticate to the Turnkey dashboard, your email is used to lookup your organization and associated credentials. Currently we do not allow multiple users to be associated with the same email address.
  </Accordion>

<Accordion title="Why do you require a public / private key pair to access Turnkey API?">
    Asymmetric cryptography offers various security benefits to you:

* Turnkey *cannot* leak your API private keys, even if compromised, because Turnkey only knows your API public keys.
    * Your API private key stays on the server you generated it for. This means there's a lower risk of key exfiltration compared to other methods where an API key, or API credentials in general, are generated in one place (web browser, company server), transported via a second (copy/paste, email, PDF document) and used in a third place (your server).
  </Accordion>

<Accordion title="Why do I need to sign the whole POST body?">
    Signing the whole payload is a way for Turnkey to know:

* That you are in possession of your API key (because we can verify the signature you attach to requests).
    * That the person or program signing is approving the current request (not just any request).

Concretely, Turnkey needs the following:

1. **The original request you sent**: this is achieved by simply receiving the HTTP request and its body
    2. **That your API key was used to approve the request**: this is achieved by checking the signature contained in the `X-Stamp` header. For this verification we need the serialized POST body, your API public key, and the signature. This is all contained in the header value.
    3. **That the request is legitimate**: this is achieved by parsing the serialized request to make sure the intent is correct. This happens all the way down in our [Secure Enclaves](/security/secure-enclaves). For example, when you send a request to create a new Private Key, our policy engine parses your original request to independently derive the type of request, the payload to sign, etc. This guards against man-in-the-middle attacks.

Turnkey would not be able to have its enclaves verify signatures and check the request intent if we didn't have your signature on the whole payload.
  </Accordion>

<Accordion title="How is a Turnkey API key different from a crypto public / private key?">
    A Turnkey API key is simply a way to authenticate requests to Turnkey. Crypto assets are not tied to it in any way.

Think about Turnkey API keys as an access-gating mechanism to Turnkey functionality. They're flexible in what they can do (you get to decide this with [Policies](/concepts/policies/overview)!), and revocable if they are lost or compromised.
  </Accordion>

<Accordion title="What happens if I lose my API key? Do I lose my crypto?">
    Losing your Turnkey API key doesn't mean you'll lose your crypto:

* By default, your API key is not able to move funds
    * If you've changed policies so that your API key is allowed to unilaterally move funds, you may be at risk. Leverage the Turnkey UI to revoke your API key as soon as possible.

Talk to our team ([hello@turnkey.com](mailto:hello@turnkey.com)) if you want to get in touch and talk more in-depth.
  </Accordion>

<Accordion title="How long is a signed activity request valid for?">
    We require a recent timestamp in the `timestampMs` field for each new activity submission.

Our secure enclaves have their own, independent, secure source of time. We currently require request timestamps to be **less than an hour old**, and **up to 5 minutes in the future**.
  </Accordion>

<Accordion title="Can I use my existing crypto private key as a Turnkey API key?">
    You can, but it doesn't mean you should. If you use your existing crypto private key as a turnkey API key, you are coupling Turnkey access with your crypto wallet. In essence, the risk profile of this key goes up. It's a bit like re-using passwords across many sites. Turnkey highly recommends creating a fresh public/private key pair if you need programmatic Turnkey access.
  </Accordion>

<Accordion title="How can I safely rotate API key credentials?">
    While we don't have an off the shelf recipe, one potential approach is:

* At sub-org creation, create your root user with 2+ API keys. One for day-to-day signing, and the other(s) securely stored.
    * If the day-to-day key is leaked, then you can use one of the secure, additional keys to remove it from all impacted sub-orgs via `ACTIVITY_TYPE_DELETE_API_KEYS`.

Reach out to our team ([hello@turnkey.com](mailto:hello@turnkey.com)) for additional guidance.
  </Accordion>
</AccordionGroup>

## Limits

<AccordionGroup>
  <Accordion title="Are there limits on how many resources I can create, or activities I can execute?">
    See [resource limits](/concepts/resource-limits).
  </Accordion>

<Accordion title="Do you have any rate limits in place in your public API?">
    Yes - Turnkey's public API enforces rate limits that vary by plan:

* **Free:** 1 request per second (RPS)
    * **Pay-as-you-go:** 1 RPS
    * **Pro:** 3 RPS
    * **Enterprise:** 60 RPS

In addition, there is a **per-suborganization limit of 10 RPS**, regardless of tier. This protects against spam and abuse (e.g., fake user creation).

Rate limit information is included in the response headers:

* `ratelimit-limit`: your plan's total RPS limit
    * `ratelimit-remaining`: current quota remaining
    * `x-rate-limit-request-forwarded-for` and `x-rate-limit-request-remote-addr`: echo back request IPs for debugging purposes

When rate limits are exceeded, an error with HTTP 429 is returned with the following message: `Too many requests. Please wait and try again in a few seconds`.

This limit is on a **per IP address** basis: if you have multiple servers making requests to the turnkey API under a different IP address, each server is subject to the 60 RPS limit individually.

Please get in touch with us ([help@turnkey.com](mailto:help@turnkey.com)) if you need this limit adjusted for your use-case.
  </Accordion>
</AccordionGroup>

## Supported functionality

<AccordionGroup>
  <Accordion title="Does Turnkey support Ethereum (EVM)?">
    Yes! See [Ethereum (EVM) support on Turnkey](networks/ethereum) for more information and concrete examples.
  </Accordion>

<Accordion title="Does Turnkey support Solana (SVM)?">
    Yes! See [Solana (SVM) support on Turnkey](networks/solana) for more information and concrete examples.
  </Accordion>

<Accordion title="Does Turnkey support Bitcoin?">
    Yes! See [Bitcoin support on Turnkey](networks/bitcoin) for more information and concrete examples.
  </Accordion>

<Accordion title="Which cryptographic curves do you support?">
    Turnkey currently supports SECP256k1 and Ed25519.
  </Accordion>

<Accordion title="Which ecosystems and chains do you support?">
    Turnkey's primitive for private keys and wallet is the **cryptographic curve** rather than specific cryptocurrencies. Our approach to supporting assets is tiered, see [this page](networks/overview) for more information.

We have deeper support for [Ethereum](networks/ethereum), [Solana](networks/solana), and [Bitcoin](networks/bitcoin).

If there are specific ecosystems or chains you'd like to see us offer deeper support for,
    please let us know by contacting us at [hello@turnkey.com](mailto:hello@turnkey.com), on [X](https://x.com/turnkeyhq/),
    or [on Slack](https://join.slack.com/t/clubturnkey/shared_invite/zt-3aemp2g38-zIh4V~3vNpbX5PsSmkKxcQ).
  </Accordion>

<Accordion title="Do you support transaction construction and broadcast?">
    Turnkey does not offer native support for transaction construction and broadcast, instead we focus on transaction signing.

We suggest you use blockchain-specific libraries, like Ethers.js for Ethereum, to construct transactions. We offer simple [scripts](https://github.com/tkhq/sdk/tree/main/examples/with-ethers/) leveraging `ethers.js` to help you with basic transaction construction.

You can use any blockchain node provider, like Infura or Alchemy, to broadcast your transactions.
  </Accordion>

<Accordion title="What does `HASH_FUNCTION_NO_OP` mean?">
    In the ECDSA context, messages are hashed before signing. Turnkey can perform this hashing for you, as we support two hash functions: `HASH_FUNCTION_KECCAK256` and `HASH_FUNCTION_SHA256` (for Ethereum and Bitcoin ecosystems respectively). If your message had already been hashed, you should use the `HASH_FUNCTION_NO_OP` option to sign the raw hash, in which case Turnkey will sign the payload as is. `HASH_FUNCTION_NO_OP` also has privacy implications: if a raw hashed message is passed in, Turnkey has no knowledge of the underlying pre-image.

As an example, in our Viem package, the message is [hashed](https://github.com/tkhq/sdk/blob/673442f025990fde6a37436bed987b42e694a64d/packages/viem/src/index.ts#L201) before [signing](https://github.com/tkhq/sdk/blob/673442f025990fde6a37436bed987b42e694a64d/packages/viem/src/index.ts#L348).
  </Accordion>

<Accordion title="What is `HASH_FUNCTION_NOT_APPLICABLE` and how does it differ from `HASH_FUNCTION_NO_OP`?">
    Unlike ECDSA, in which a message is hashed as a separate step *before* signing, when using Ed25519, hashing is performed *during* signature computation, and thus cannot be skipped (for more details on the standard, see [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1): `“Ed25519 is EdDSA instantiated with: …H(x) = SHA-512"`). As a result, we have a special `HASH_FUNCTION_NOT_APPLICABLE` option for when you use ed25519/EdDSA.

An example for this case can be found in our [Solana signer](https://github.com/tkhq/sdk/blob/d9ed2aefc92d298826a40e821f959b019ea1936f/packages/solana/src/index.ts#L64).
  </Accordion>
</AccordionGroup>

## Guidance

<AccordionGroup>
  <Accordion title="Do you have a status page?">
    Yes, we report critical incidents at [turnkey-status.com](https://www.turnkey-status.com/).
  </Accordion>

<Accordion title="How do you recommend testing the Turnkey API and functionality safely?">
    Typically we recommend that you create "test" organizations to test the API and functionality freely. When you are ready to go to production, use a "main" organization used for production only.

To do this you can use email aliases: if `firstname@domain.com` is your email, you can sign up for a new Turnkey organization with `firstname+test@domain.com` to have a test playground.

If you need many test organizations or if you have specific questions, our team is happy to help you get set up.
  </Accordion>

<Accordion title="How do pricing and billing work?">
    Turnkey is priced per signature, i.e. any transaction or raw payload successfully signed by a private key created on Turnkey. Turnkey offers 25 free signatures each month. To execute more than 25 transactions in a given month, you are required to have a credit card on file or active enterprise plan on your account. To upgrade your plan, navigate to Account Settings from the menu in the top right-hand corner in the Turnkey dashboard and follow the instructions.

For more information about pricing and billing, check out the [pricing page](https://www.turnkey.com/pricing).
  </Accordion>

<Accordion title="Where else can I get help with my Turnkey implementation?">
    Join our slack community [here](https://join.slack.com/t/clubturnkey/shared_invite/zt-3aemp2g38-zIh4V~3vNpbX5PsSmkKxcQ) to get support with your integration, share product feedback, and connect with other crypto builders. Or, reach out directly to [help@turnkey.com.](mailto:help@turnkey.com.) Teams that are looking for more in-depth integration support can upgrade to an Enterprise plan via [hello@turnkey.com](mailto:hello@turnkey.com).
  </Accordion>

<Accordion title="What is your data deletion policy?">
    To request the deletion of your parent organization from our records, please email us at [privacy@turnkey.com](mailto:privacy@turnkey.com).
  </Accordion>

<Accordion title="Is my country supported?">
    Turnkey is not currently available to users in any countries currently subject to US OFAC sanctions.
  </Accordion>

<Accordion title="Where can I learn more about Turnkey's internal architecture?">
    Check out our whitepaper, available at [whitepaper.turnkey.com](https://whitepaper.turnkey.com)! It covers our foundations and architecture in great detail.
  </Accordion>
</AccordionGroup>

# addOauthProvider()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-add-oauth-provider

Adds an OAuth provider to the user.

<ul>
  <li>This function adds an OAuth provider (e.g., Google, Apple) to the user account.</li>
  <li>If a userId is provided, it adds the provider for that specific user; otherwise, it uses the current session's userId.</li>
  <li>Automatically checks if an account already exists for the provided OIDC token and prevents duplicate associations.</li>
  <li>If the user's email is not set or not verified, attempts to update and verify the email using the email from the OIDC token.</li>
  <li>Handles session management and error reporting for the add provider flow.</li>
  <li>Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L3587">**clients**/core.ts:3587</a></p>

<ParamField type="AddOauthProviderParams">
  <Expandable title="params details">
    <NestedParam type="string">
      OIDC token for the OAuth provider.
    </NestedParam>

<NestedParam type="string">
      organization ID to specify the sub-organization (defaults to the current session's organizationId).
    </NestedParam>

<NestedParam type="string">
      name of the OAuth provider to add (e.g., "Google", "Apple").
    </NestedParam>

<NestedParam type="StamperType">
      parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
    </NestedParam>

<NestedParam type="string">
      user ID to add the provider for a specific user (defaults to current session's userId).
    </NestedParam>
  </Expandable>
</ParamField>

A successful response returns the following fields:

<ResponseField name="returns" type="string[]">
  A promise that resolves to an array of provider IDs associated with the user.
</ResponseField>

# addPasskey()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-add-passkey

Adds a new passkey authenticator for the user.

<ul>
  <li>This function prompts the user to create a new passkey (WebAuthn/FIDO2) and adds it as an authenticator for the user.</li>
  <li>Handles both web and React Native environments, automatically selecting the appropriate passkey creation flow.</li>
  <li>If a userId is provided, the passkey is added for that specific user; otherwise, it uses the current session's userId.</li>
  <li>The passkey's name and display name can be customized; if not provided, defaults are generated.</li>
  <li>The resulting passkey attestation and challenge are registered with Turnkey as a new authenticator.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L3797">**clients**/core.ts:3797</a></p>

<ParamField type="AddPasskeyParams">
  <Expandable title="params details">
    <NestedParam type="string">
      display name of the passkey (defaults to the value of `name`).
    </NestedParam>

<NestedParam type="string">
      name of the passkey (defaults to "Turnkey Passkey-`timestamp`").
    </NestedParam>

<NestedParam type="string">
      organization ID to specify the sub-organization (defaults to the current session's organizationId).
    </NestedParam>

<NestedParam type="StamperType">
      parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
    </NestedParam>

<NestedParam type="string">
      user ID to add the passkey for a specific user (defaults to the current session's userId).
    </NestedParam>
  </Expandable>
</ParamField>

A successful response returns the following fields:

<ResponseField name="returns" type="string[]">
  A promise that resolves to an array of authenticator IDs for the newly added passkey(s).
</ResponseField>

# buildWalletLoginRequest()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-build-wallet-login-request

Builds and signs a wallet login request without submitting it to Turnkey.

<ul>
  <li>This function prepares a signed request for wallet authentication, which can later be used</li>
</ul>

to log in or sign up a user with Turnkey.

<ul>
  <li>It initializes the wallet stamper, ensures a valid session public key (generating one if needed),</li>
</ul>

and signs the login intent with the connected wallet.

<ul>
  <li>For Ethereum wallets, derives the public key from the stamped request header.</li>
  <li>For Solana wallets, retrieves the public key directly from the connected wallet.</li>
  <li>The signed request is not sent to Turnkey immediately; it is meant to be used in a subsequent flow</li>
</ul>

(e.g., `loginOrSignupWithWallet`) where sub-organization existence is verified or created first.

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L823">**clients**/core.ts:823</a></p>

<ParamField type="BuildWalletLoginRequestParams">
  <Expandable title="params details">
    <NestedParam type="string">
      optional session expiration time in seconds (defaults to the configured default).
    </NestedParam>

<NestedParam type="string">
      optional pre-generated session public key (auto-generated if not provided).
    </NestedParam>

<NestedParam type="WalletProvider">
      the wallet provider used for authentication and signing.
    </NestedParam>
  </Expandable>
</ParamField>

A successful response returns the following fields:

<ResponseField name="returns" type="BuildWalletLoginRequestResult">
  A promise resolving to an object containing:

* `signedRequest`: the signed wallet login request.
  * `publicKey`: the public key associated with the signed request.

# clearAllSessions()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-clear-all-sessions

Clears all sessions and resets the active session state.

<ul>
  <li>This function removes all session data from the client and persistent storage, including all associated key pairs.</li>
  <li>Iterates through all stored session keys, clearing each session and deleting its corresponding API key pair.</li>
  <li>After clearing, there will be no active session, and all session-related data will be removed from local storage.</li>
  <li>Throws an error if no sessions exist or if there is an error during the clearing process.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L4572">**clients**/core.ts:4572</a></p>

<p>No parameters.</p>

A successful response returns the following fields:

<ResponseField name="returns" type="void">
  A promise that resolves when all sessions are successfully cleared.
</ResponseField>

# clearSession()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-clear-session

Clears the session associated with the specified session key, or the active session by default.

<ul>
  <li>This function deletes the session and its associated key pair from storage.</li>
  <li>If a sessionKey is provided, it will clear the session under that key; otherwise, it will clear the default (active) session.</li>
  <li>Removes the session data from local storage and deletes the corresponding API key pair from the key store.</li>
  <li>Throws an error if the session does not exist or if there is an error during the clearing process.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L4537">**clients**/core.ts:4537</a></p>

<ParamField type="ClearSessionParams">
  <Expandable title="params details">
    <NestedParam type="string">
      session key to clear the session under (defaults to the default session key).
    </NestedParam>
  </Expandable>
</ParamField>

A successful response returns the following fields:

<ResponseField name="returns" type="void">
  A promise that resolves when the session is successfully cleared.
</ResponseField>

# clearUnusedKeyPairs()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-clear-unused-key-pairs

Clears any unused API key pairs from persistent storage.

<ul>
  <li>This function scans all API key pairs stored in indexedDB and removes any key pairs that are not associated with a session in persistent storage.</li>
  <li>Ensures that only key pairs referenced by existing sessions are retained, preventing orphaned or stale key pairs from accumulating.</li>
  <li>Iterates through all stored session keys and builds a map of in-use public keys, then deletes any key pairs not present in this map.</li>
  <li>Intended to be called after session changes (e.g., login, logout, session replacement) to keep key storage clean and secure.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L4798">**clients**/core.ts:4798</a></p>

<p>No parameters.</p>

A successful response returns the following fields:

<ResponseField name="returns" type="void">
  A promise that resolves when all unused key pairs are successfully cleared.
</ResponseField>

# completeOauth()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-complete-oauth

Completes the OAuth authentication flow by either signing up or logging in the user, depending on whether a sub-organization already exists for the provided OIDC token.

<ul>
  <li>This function first checks if there is an existing sub-organization associated with the OIDC token.</li>
  <li>If a sub-organization exists, it proceeds with the OAuth login flow.</li>
  <li>If no sub-organization exists, it creates a new sub-organization and completes the sign-up flow.</li>
  <li>Optionally accepts a custom OAuth provider name, session key, and additional sub-organization creation parameters.</li>
  <li>Handles session storage and management, and supports invalidating existing sessions if specified.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L1661">**clients**/core.ts:1661</a></p>

<ParamField type="CompleteOauthParams">
  <Expandable title="params details">
    <NestedParam type="CreateSubOrgParams">
      parameters for sub-organization creation (e.g., authenticators, user metadata).
    </NestedParam>

<NestedParam type="object[]">
        list of authenticators
      </NestedParam>

<NestedParam type="CustomWallet">
        custom wallets to create during sub-org creation time
      </NestedParam>

<Expandable title="customWallet details">
        <NestedParam type="v1WalletAccountParams[]">
          list of wallet accounts to create
        </NestedParam>

<NestedParam type="string">
          name of the wallet created
        </NestedParam>
      </Expandable>

<NestedParam type="Provider[]">
        list of oauth providers
      </NestedParam>

<NestedParam type="string">
        name of the sub-organization
      </NestedParam>

<NestedParam type="string">
        email of the user
      </NestedParam>

<NestedParam type="string">
        phone number of the user
      </NestedParam>

<NestedParam type="string">
        verification token if email or phone number is provided
      </NestedParam>
    </Expandable>

<NestedParam type="boolean">
      flag to invalidate existing sessions for the user.
    </NestedParam>

<NestedParam type="string">
      OIDC token received after successful authentication with the OAuth provider.
    </NestedParam>

<NestedParam type="string">
      name of the OAuth provider (defaults to a generated name with a timestamp).
    </NestedParam>

<NestedParam type="string">
      public key to use for authentication. Must be generated prior to calling this function, this is because the OIDC nonce has to be set to `sha256(publicKey)`.
    </NestedParam>

<NestedParam type="string">
      session key to use for session creation (defaults to the default session key).
    </NestedParam>
  </Expandable>
</ParamField>

A successful response returns the following fields:

<ResponseField name="returns" type="BaseAuthResult & object">
  A promise that resolves to an object containing:

* `sessionToken`: the signed JWT session token.
  * `action`: whether the flow resulted in a login or signup (AuthAction).
</ResponseField>

# completeOtp()
Source: https://docs.turnkey.com/generated-docs/core/turnkey-client-complete-otp

Completes the OTP authentication flow by verifying the OTP code and then either signing up or logging in the user.

<ul>
  <li>This function first verifies the OTP code for the provided contact and OTP type.</li>
  <li>If the contact is not associated with an existing sub-organization, it will automatically create a new sub-organization and complete the sign-up flow.</li>
  <li>If the contact is already associated with a sub-organization, it will complete the login flow.</li>
  <li>Supports passing a custom public key for authentication, invalidating existing session, specifying a session key, and providing additional sub-organization creation parameters.</li>
  <li>Handles both email and SMS OTP types.</li>
</ul>

<p><strong>Package:</strong> <code>core</code></p>

<p><strong>Defined in:</strong> <a href="https://github.com/tkhq/sdk/blob/main/packages/core/src/__clients__/core.ts#L1569">**clients**/core.ts:1569</a></p>

<ParamField type="CompleteOtpParams">
  <Expandable title="params details">
    <NestedParam type="string">
      contact information for the user (e.g., email address or phone number).
    </NestedParam>

<NestedParam type="CreateSubOrgParams">
      parameters for sub-organization creation (e.g., authenticators, user metadata).
    </NestedParam>