Add an Additional Passkey

Overview

This guide demonstrates how to add a new credential (specifically, a passkey) to an existing wallet using the Turnkey SDK.

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.

What's the purpose of the rpId?

The rpId is used in WebAuthn to uniquely identify the server that the passkey is associated with. The rpId is typically the effective domain of the web application, which is the domain portion of the URL without any subdomains. For example, if your application is hosted at app.example.com, the rpId would typically be example.com. This ensures that credentials are scoped to the correct domain and cannot be used by other domains, enhancing security.

Next.js
TypeScript

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_TURNKEY_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>;
}

Create a new file src/add-passkey.ts:

src/add-passkey.ts
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

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.

note

The user object which gets stored in local storage is defined as follows:

export interface User {
  userId: string;
  username: string;
  organization: SubOrganization;
  readOnlySession?: ReadOnlySession;
}

Next.js
TypeScript

app/add-passkey.tsx
// ... previous code

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

  const login = async () => {
    const response = await passkeyClient?.login();
    if (response.organizationId) {
      console.log("User authenticated successfully");
    } else {
      console.log("User authentication failed");
    }
  };

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

  return (
    <div>
      <button onClick={login}>Login</button>
      {/* We'll more add UI elements here */}
    </div>
  );
}

src/add-passkey.ts
// ... previous code

const login = async () => {
  const response = await passkeyClient.login();
  if (response.organizationId) {
    console.log("User authenticated successfully");
  } else {
    console.log("User authentication failed");
  }
};

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.

Next.js
TypeScript

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>
  );
}

src/add-passkey.ts
// ... previous code

const getCurrentUser = 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;
};

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.

info

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.

Next.js
TypeScript

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 (/* ... */);
}

src/add-passkey.ts
// ... 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;
};

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.

Next.js
TypeScript

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>
  );
}

Complete add-passkey.tsx component

app/add-passkey.tsx
"use client";

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

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

  const login = async () => {
    const response = await passkeyClient?.login();
    if (response.organizationId) {
      console.log("User authenticated successfully");
    } else {
      console.log("User authentication failed");
    }
  };

  const getUser = async () => {
    const user = await turnkey?.getCurrentUser();
    if (user) {
      console.log("User retrieved successfully");
    }
    return user;
  };

  const createNewPasskey = async (user: User) => {
    const credential = await passkeyClient?.createUserPasskey({
      publicKey: {
        rp: {
          name: "Wallet Passkey",
        },
        user: {
          name: user.username,
          displayName: user.username,
        },
      },
    });

    return credential;
  };

  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,
    });

    if (authenticatorsResponse?.activity.id) {
      console.log("Authenticator created successfully");
    }
  };

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

src/add-passkey.ts
// ... previous code

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

  // Check if the credential was created successfully
  if (!credential) {
    console.log("Credential not created");
    return;
  }

  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");
  }
};

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:

To login
To create the new passkey
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:

To login and create a session
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.

Next.js
TypeScript

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 (/* ... */);
}

1. Initialize the iframe client

We'll create a new function to initialize the iframe client and inject the read/write session.

src/add-passkey.ts
// ... previous code

const getIframeClient = async () => {
  const iframeContainerId = "turnkey-recovery-iframe-container-id";

  const authIframeClient = await turnkey.iframeClient(
    document.getElementById(iframeContainerId),
  );

  const readWriteSession = await turnkey?.getReadWriteSession();

  if (readWriteSession) {
    const injected = await authIframeClient?.injectCredentialBundle(
      readWriteSession.authBundle,
    );
  }

  return authIframeClient;
};

note

When using the TypeScript SDK, you'll need to ensure that the HTML element exists somewhere in the rendered DOM.

<div id="turnkey-recovery-iframe-container-id" />

2. Update the `addPasskey` function

We'll update the addPasskey function to use the iframe client to authenticate the request to create a new authenticator.

src/add-passkey.ts
// ... previous code

const addPasskey = async () => {
  // ... previous code

  const iframeClient = await getIframeClient();

  const authenticatorsResponse = await iframeClient.createAuthenticators({
    // ...
  });
  // ... rest of the code remains the same
};

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.

Overview​

Initialize the Passkey Client​

Authenticate the User​

Get the current user​

Create User Passkey​

Add the credential to the wallet​

Optional: Read/Write Sessions​

1. Initialize the iframe client​

2. Update the addPasskey function​

Conclusion​