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");
const walletBundle = await iframeClient.extractWalletEncryptedBundle();
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.
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
