​
Overview

The @turnkey/sdk-browser package enables developers to build browser-based applications that interact with the Turnkey API using multiple authentication methods.

It includes:

  • indexedDbClient: The recommended client for authentication and session creation using secure, unextractable P-256 keys stored in the browser’s IndexedDB.
  • passkeyClient: For passkey registration and signing flows.
  • iframeClient: Used for secure credential injection and import/export operations.
  • walletClient: For signing with external wallets like MetaMask.

If you’re building with React, check out our @turnkey/sdk-react package.

​
Installation

npm install @turnkey/sdk-browser

​
Initialization

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

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

​
Authentication

​
loginWithPasskey

Creates a session for a user authenticated with a passkey. The session is stored in localStorage, and signing operations are done with an unextractable keypair stored in IndexedDB.

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

const publicKey = await indexedDbClient.getPublicKey();

await passkeyClient.loginWithPasskey({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey,
  expirationSeconds: 900,
});

​
loginWithBundle

Used to authenticate a user with a credential bundle (e.g. from Email Auth). Must be used from an iframeClient.

const iframeClient = await turnkey.iframeClient({
  iframeUrl: "https://auth.turnkey.com",
  iframeContainer: document.getElementById("iframe-container"),
});

await iframeClient.loginWithBundle({
  bundle: "credential-bundle",
  expirationSeconds: 900,
});

​
loginWithSession

Logs in using a session string (JWT) that was created elsewhere (e.g. server action). Only valid on indexedDbClient.

await indexedDbClient.loginWithSession("jwt-session-string");

​
loginWithWallet

Uses a Web3 wallet to authenticate the user and store a read-write session.

const walletClient = turnkey.walletClient(new EthereumWallet());

await walletClient.loginWithWallet({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey: await walletClient.getPublicKey(),
  expirationSeconds: 900,
});

​
refreshSession

Refreshes the current session and extends its expiration time. The correct publicKey must be provided for read-write sessions.

await indexedDbClient.refreshSession({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey: await indexedDbClient.getPublicKey(),
  expirationSeconds: 900,
});

​
IndexedDbClient

The indexedDbClient is the recommended way to manage secure keys for session-based authentication.

​
init

Initializes and stores an unextractable P-256 keypair in the browser.

await indexedDbClient.init();

​
getPublicKey

Returns the base64url-encoded public key of the stored keypair.

const publicKey = await indexedDbClient.getPublicKey();

​
clear

Removes all key material from IndexedDB.

await indexedDbClient.clear();

​
resetKeyPair

Deletes and regenerates the stored keypair.

await indexedDbClient.resetKeyPair();

​
IframeClient

Primarily used for secure credential injection and key export/import.

​
injectCredentialBundle

Injects a read-write session credential bundle into the iframe.

await iframeClient.injectCredentialBundle("bundle");

​
injectWalletExportBundle

await iframeClient.injectWalletExportBundle("bundle", "org-id");

​
injectKeyExportBundle

await iframeClient.injectKeyExportBundle("bundle", "org-id", "PEM");

​
injectImportBundle

await iframeClient.injectImportBundle("bundle", "org-id", "user-id");

​
extractWalletEncryptedBundle

const walletBundle = await iframeClient.extractWalletEncryptedBundle();

​
extractKeyEncryptedBundle

const keyBundle = await iframeClient.extractKeyEncryptedBundle();

​
getEmbeddedPublicKey

const pubkey = await iframeClient.getEmbeddedPublicKey();

​
initEmbeddedKey

const pubkey = await iframeClient.initEmbeddedKey();

​
clearEmbeddedKey

await iframeClient.clearEmbeddedKey();

​
PasskeyClient

​
createUserPasskey

Registers a new passkey using WebAuthn.

const passkey = await passkeyClient.createUserPasskey({
  publicKey: {
    rp: { name: "My App" },
    user: { name: "user@example.com", displayName: "User" },
  },
});

​
WalletClient

​
getPublicKey

const publicKey = await walletClient.getPublicKey();

​
getWalletInterface

const wallet = walletClient.getWalletInterface();

​
Session Management

​
getSession

Returns the active session if it exists and hasn’t expired.

const session = await turnkey.getSession();

​
getRawSession

Returns the raw JWT string if a valid session exists.

const jwt = await turnkey.getRawSession();

​
logout

Clears all stored session and client data.

await turnkey.logout();

​
Top-Level SDK Methods

​
passkeyClient()

const passkeyClient = turnkey.passkeyClient();

​
indexedDbClient()

const indexedDbClient = await turnkey.indexedDbClient();

​
iframeClient()

const iframeClient = await turnkey.iframeClient({
  iframeUrl: "https://auth.turnkey.com",
  iframeContainer: document.getElementById("iframe-container"),
});

​
walletClient(wallet)

const walletClient = turnkey.walletClient(new EthereumWallet());

​
serverSign(methodName, params, [serverSignUrl])

const result = await turnkey.serverSign("method", [param1, param2]);

​
Examples

Implementing an embedded wallet authentication flow with Passkeys

Implementing an embedded wallet authentication flow with email

Signing Transactions

​
Overview

The @turnkey/sdk-browser package enables developers to build browser-based applications that interact with the Turnkey API using multiple authentication methods.

It includes:

  • indexedDbClient: The recommended client for authentication and session creation using secure, unextractable P-256 keys stored in the browser’s IndexedDB.
  • passkeyClient: For passkey registration and signing flows.
  • iframeClient: Used for secure credential injection and import/export operations.
  • walletClient: For signing with external wallets like MetaMask.

If you’re building with React, check out our @turnkey/sdk-react package.

​
Installation

npm install @turnkey/sdk-browser

​
Initialization

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

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

​
Authentication

​
loginWithPasskey

Creates a session for a user authenticated with a passkey. The session is stored in localStorage, and signing operations are done with an unextractable keypair stored in IndexedDB.

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

const publicKey = await indexedDbClient.getPublicKey();

await passkeyClient.loginWithPasskey({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey,
  expirationSeconds: 900,
});

​
loginWithBundle

Used to authenticate a user with a credential bundle (e.g. from Email Auth). Must be used from an iframeClient.

const iframeClient = await turnkey.iframeClient({
  iframeUrl: "https://auth.turnkey.com",
  iframeContainer: document.getElementById("iframe-container"),
});

await iframeClient.loginWithBundle({
  bundle: "credential-bundle",
  expirationSeconds: 900,
});

​
loginWithSession

Logs in using a session string (JWT) that was created elsewhere (e.g. server action). Only valid on indexedDbClient.

await indexedDbClient.loginWithSession("jwt-session-string");

​
loginWithWallet

Uses a Web3 wallet to authenticate the user and store a read-write session.

const walletClient = turnkey.walletClient(new EthereumWallet());

await walletClient.loginWithWallet({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey: await walletClient.getPublicKey(),
  expirationSeconds: 900,
});

​
refreshSession

Refreshes the current session and extends its expiration time. The correct publicKey must be provided for read-write sessions.

await indexedDbClient.refreshSession({
  sessionType: "SESSION_TYPE_READ_WRITE",
  publicKey: await indexedDbClient.getPublicKey(),
  expirationSeconds: 900,
});

​
IndexedDbClient

The indexedDbClient is the recommended way to manage secure keys for session-based authentication.

​
init

Initializes and stores an unextractable P-256 keypair in the browser.

await indexedDbClient.init();

​
getPublicKey

Returns the base64url-encoded public key of the stored keypair.

const publicKey = await indexedDbClient.getPublicKey();

​
clear

Removes all key material from IndexedDB.

await indexedDbClient.clear();

​
resetKeyPair

Deletes and regenerates the stored keypair.

await indexedDbClient.resetKeyPair();

​
IframeClient

Primarily used for secure credential injection and key export/import.

​
injectCredentialBundle

Injects a read-write session credential bundle into the iframe.

await iframeClient.injectCredentialBundle("bundle");

​
injectWalletExportBundle

await iframeClient.injectWalletExportBundle("bundle", "org-id");

​
injectKeyExportBundle

await iframeClient.injectKeyExportBundle("bundle", "org-id", "PEM");

​
injectImportBundle

await iframeClient.injectImportBundle("bundle", "org-id", "user-id");

​
extractWalletEncryptedBundle

const walletBundle = await iframeClient.extractWalletEncryptedBundle();

​
extractKeyEncryptedBundle

const keyBundle = await iframeClient.extractKeyEncryptedBundle();

​
getEmbeddedPublicKey

const pubkey = await iframeClient.getEmbeddedPublicKey();

​
initEmbeddedKey

const pubkey = await iframeClient.initEmbeddedKey();

​
clearEmbeddedKey

await iframeClient.clearEmbeddedKey();

​
PasskeyClient

​
createUserPasskey

Registers a new passkey using WebAuthn.

const passkey = await passkeyClient.createUserPasskey({
  publicKey: {
    rp: { name: "My App" },
    user: { name: "user@example.com", displayName: "User" },
  },
});

​
WalletClient

​
getPublicKey

const publicKey = await walletClient.getPublicKey();

​
getWalletInterface

const wallet = walletClient.getWalletInterface();

​
Session Management

​
getSession

Returns the active session if it exists and hasn’t expired.

const session = await turnkey.getSession();

​
getRawSession

Returns the raw JWT string if a valid session exists.

const jwt = await turnkey.getRawSession();

​
logout

Clears all stored session and client data.

await turnkey.logout();

​
Top-Level SDK Methods

​
passkeyClient()

const passkeyClient = turnkey.passkeyClient();

​
indexedDbClient()

const indexedDbClient = await turnkey.indexedDbClient();

​
iframeClient()

const iframeClient = await turnkey.iframeClient({
  iframeUrl: "https://auth.turnkey.com",
  iframeContainer: document.getElementById("iframe-container"),
});

​
walletClient(wallet)

const walletClient = turnkey.walletClient(new EthereumWallet());

​
serverSign(methodName, params, [serverSignUrl])

const result = await turnkey.serverSign("method", [param1, param2]);

​
Examples

Implementing an embedded wallet authentication flow with Passkeys

Implementing an embedded wallet authentication flow with email

Signing Transactions