​
Initialize the Passkey Client

Begin by initializing the Turnkey SDK by passing in a config object containing:
  • rpId: The Relying Party Identifier, which is the effective domain of your application.
  • 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.
First, wrap your application with the TurnkeyProvider in your app/layout.tsx file:
app/layout.tsx
import { TurnkeyProvider } from "@turnkey/sdk-react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <TurnkeyProvider
          config={{
            // The domain of your application
            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>
  );
}
Then, create a new file app/add-passkey.tsx where we’ll implement the passkey functionality:
app/add-passkey.tsx
"use client";

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

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

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

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

​
Authenticate the User

Now that that the Passkey Client is initialized, we’ll call the login function which will prompt the user to authenticate with their passkey. Additionally, this function will set the current user in local storage upon successful authentication, which will be used later when creating an additional authenticator.
The user object which gets stored in local storage is defined as follows:
export interface User {
  userId: string;
  username: string;
  organization: SubOrganization;
  readOnlySession?: ReadOnlySession;
}
app/add-passkey.tsx
// ... previous code

export default function AddPasskey() {
  // We'll need the base Turnkey client to get the current user
  const { passkeyClient, turnkey } = useTurnkey();

  // ... previous code

  const getUser = async () => {
    // Get the current user from local storage,
    // we'll need the `userId` to create the authenticator in the next step
    const user = await turnkey?.getCurrentUser();
    if (user) {
      console.log("User retrieved successfully");
    }
    // return the user to be used in the next step
    return user;
  };

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

​
Get the current user

Before creating a new passkey, we’ll get the current user. This function will retrieve the user from local storage, which was set after calling the login function. We’ll need the userId to create the authenticator in the final step.
app/add-passkey.tsx
// ... previous code

export default function AddPasskey() {
  // We'll need the base Turnkey client to get the current user
  const { passkeyClient, turnkey } = useTurnkey();

  // ... previous code

  const getUser = async () => {
    // Get the current user from local storage,
    // we'll need the `userId` to create the authenticator in the next step
    const user = await turnkey?.getCurrentUser();
    if (user) {
      console.log("User retrieved successfully");
    }
    // return the user to be used in the next step
    return user;
  };

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

​
Create User Passkey

Now that you have authenticated the user, you can call the createUserPasskey function to create a new user passkey credential. 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 and used for future authentication. Once the credential is created, we’ll use it in the next step to create a new authenticator for the user.
The credential 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.
app/add-passkey.tsx
// ... previous code

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

  // ... previous code

  // We'll pass the user object returned from `getUser` to this function
  const createNewPasskey = async (user: User) => {
    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: user.username,
          displayName: user.username,
        },
      },
    });

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

  return (/* ... */);
}

​
Add the credential to the wallet

Now that you have created a new user passkey credential, we’ll use this credential to create a new passkey authenticator for the user. We’ll need the userId to create the authenticator, so we’ll get the current user first. This value comes from local storage which was set in the previous step when the user successfully authenticated via the login function.
app/add-passkey.tsx
// ... previous code

export default function AddPasskey() {
  const { passkeyClient, turnkey } = useTurnkey();

  // ... previous code

  const addPasskey = async () => {
    const user = await getUser();
    const credential = await createNewPasskey(user);

    const authenticatorsResponse = await passkeyClient.createAuthenticators({
      authenticators: [
        {
          authenticatorName: "New Passkey Authenticator",
          challenge: credential.encodedChallenge,
          attestation: credential.attestation,
        },
      ],
      userId: user.userId,
    });

    // Check if the authenticator was created successfully
    if (authenticatorsResponse?.activity.id) {
      console.log("Authenticator created successfully");
    }
  };

  return (
    <div>
      {/* Add a button to add the passkey to the wallet */}
      <button onClick={addPasskey}>AddPasskey</button>
      <button onClick={login}>Login</button>
    </div>
  );
}

​
Optional: Read/Write Sessions

In some cases, you may want to create a read/write session for the user to reduce the number of passkey prompts. This session can be used instead of the passkey to sign requests to Turnkey’s API to improve the user experience. In the this tutorial we used the passkey to authenticate the request to create a new authenticator. The result is that the user will be prompted 3 times:
  1. To login
  2. To create the new passkey
  3. To authenticate the request to create a new authenticator
By creating a read/write session, we can reduce the number of passkey prompts to 2:
  1. To login and create a session
  2. To authenticate the request to create a new authenticator
To create a read/write session, we simply replace passkeyClient.login() with passkeyClient.loginWithReadwriteSession():
src/add-passkey.ts
// ... previous code

const login = async () => {
  const response = await passkeyClient.loginWithReadwriteSession();
  // ... previous code
};
Assuming the login is successful, a read/write session object will be stored in local storage. We’ll use the stored session in conjunction with the iframe client to authenticate the create authenticator request.
We’ll use the active client returned from the useTurnkey hook which will be initialized with the read/write session. The rest of the code remains the same.
app/add-passkey.tsx
// ... previous code

export default function AddPasskey() {
  const { getActiveClient, turnkey } = useTurnkey();

  // ... previous code

  const addPasskey = async () => {
    const user = await getUser();
    const credential = await createNewPasskey(user);

    // Get the active client which returns the iframe client initialized with the read/write session
    const activeClient = await getActiveClient();

    // Since we're using the read/write session this won't prompt the user
    const authenticatorsResponse = await activeClient.createAuthenticators({
      // ...
    });

    // ... rest of the code remains the same
  };

  return (/* ... */);
}

​
Conclusion

In this guide, we’ve walked through the process of adding a new credential to an existing wallet using the Turnkey SDK. By following these steps, you can improve the usability of your application by allowing users to create multiple authentication methods. This flexibility enables users to add a hardware security device like a Yubikey, or a native passkey via providers like iCloud keychain or 1Password, enhancing their overall experience with your application. For a complete example, check out our demo embedded wallet.