@turnkey/core

Low-level TypeScript client for the Turnkey API

@turnkey/core is the low-level TypeScript client for the Turnkey API. It is designed for frameworks and environments where @turnkey/react-wallet-kit is not available, including Angular, Vue, Svelte, and highly custom integrations. It also serves as the foundation for React Native via @turnkey/react-native-wallet-kit.

Most React applications should use @turnkey/react-wallet-kit instead of @turnkey/core directly. The wallet kit provides a complete authentication and wallet management experience on top of this package.

@turnkey/core supersedes @turnkey/sdk-browser. New integrations should use this package.

Installation

npm install @turnkey/core

The TurnkeyClient class

TurnkeyClient is the main entry point for all Turnkey operations. It manages stampers (for request authentication), session storage, wallet connections, and the HTTP client that communicates with the Turnkey API and Auth Proxy.

Constructor

import { TurnkeyClient } from "@turnkey/core";

const client = new TurnkeyClient({
  organizationId: "your-organization-id",
  authProxyConfigId: "your-auth-proxy-config-id",
});

// Initialize the client (required before calling any methods)
await client.init();

TurnkeyClient accepts a TurnkeySDKClientConfig object:

organizationId · string · required

Your Turnkey parent organization ID.

authProxyConfigId · string

The Auth Proxy configuration ID. Required when using Auth Proxy flows.

apiBaseUrl · string

Turnkey API base URL. Defaults to https://api.turnkey.com.

authProxyUrl · string

Auth Proxy base URL. Defaults to https://authproxy.turnkey.com.

passkeyConfig · object

Configuration for the passkey stamper. Required to use passkey authentication.

walletConfig · object

Configuration for the external wallet manager. Required to use wallet-based authentication or connecting external wallets.

defaultStamperType · StamperType

The default stamper to use for requests that require signing (ApiKey, Passkey, or Wallet).

Initialization

Call client.init() once before using any other methods. This initializes storage, stampers, and the HTTP client in parallel:

await client.init();

Creating an HTTP client

You can create additional TurnkeySDKClientBase instances with different configurations:

const httpClient = client.createHttpClient({
  organizationId: "suborg-id",
  authProxyConfigId: "another-config-id",
});

Authentication methods

Passkey

// Create a new passkey
const passkey = await client.createPasskey({ name: "My Passkey" });

// Log in with an existing passkey
const result = await client.loginWithPasskey();
// result.sessionToken — signed JWT

// Sign up a new user with a passkey
const result = await client.signUpWithPasskey({
  passkeyDisplayName: "My Passkey",
});

External wallet

// Fetch available wallet providers (MetaMask, Phantom, etc.)
const providers = await client.fetchWalletProviders();

// Connect a wallet account
const address = await client.connectWalletAccount(providers[0]);

// Log in with a connected wallet
const result = await client.loginWithWallet({ walletProvider: providers[0] });

// Sign up with a wallet
const result = await client.signUpWithWallet({ walletProvider: providers[0] });

// Log in or sign up — creates a sub-org if none exists
const result = await client.loginOrSignupWithWallet({ walletProvider: providers[0] });

OTP (email and SMS)

import { OtpType } from "@turnkey/core";

// Send an OTP
const otpId = await client.initOtp({
  otpType: OtpType.Email,
  contact: "[e-mail]",
});

// Verify the OTP code
const { subOrganizationId, verificationToken } = await client.verifyOtp({
  otpId,
  otpCode: "123456",
  contact: "[e-mail]",
  otpType: OtpType.Email,
});

// Log in using the verification token
const result = await client.loginWithOtp({
  subOrganizationId,
  verificationToken,
});

OAuth

// Initiate Google OAuth (opens popup or redirects)
await client.loginWithOauth({
  oidcToken: "id-token-from-google",
  subOrganizationId: "suborg-id",
});

Session management

TurnkeyClient manages sessions using a built-in storage manager. Sessions are keyed by a sessionKey string.

Method	Description
storeSession(params)	Persist a session token under a given session key
getSession(params?)	Retrieve the active or a specific session
setActiveSession(params)	Make a specific session the active one
refreshSession(params?)	Refresh the active or a specific session before expiry
logout(params?)	Clear the active or a specific session and delete associated key pairs

// Store a session
await client.storeSession({
  sessionToken: "signed-jwt",
  sessionKey: "my-session",
});

// Log out from the active session
await client.logout();

Wallet methods

Method	Description
fetchWallets(params?)	Retrieve the user’s embedded wallets
fetchWalletAccounts(params?)	Retrieve accounts for a specific wallet
createWallet(params)	Create a new embedded wallet
exportWallet(params)	Export a wallet as an encrypted bundle
exportPrivateKey(params)	Export a private key as an encrypted bundle
exportWalletAccount(params)	Export a wallet account as an encrypted bundle
importWallet(params)	Import a wallet from an encrypted bundle
importPrivateKey(params)	Import a private key from an encrypted bundle

Signing methods

Method	Description
signMessage(params)	Sign an arbitrary message with a wallet account
signTransaction(params)	Sign a transaction
signAndSendTransaction(params)	Sign and broadcast a transaction
ethSendTransaction(params)	Send an EVM transaction
solSendTransaction(params)	Send a Solana transaction

Integration with stampers

@turnkey/core integrates with the following stamper packages for request signing:

@turnkey/api-key-stamper

Signs requests with an API key pair. Used for server-side and session-based authentication.

@turnkey/webauthn-stamper

Signs requests using a WebAuthn passkey credential. Used for passkey-based authentication.

Stampers are initialized automatically by TurnkeyClient.init() based on the provided config. You can also supply custom stamper instances to the constructor:

import { ApiKeyStamper } from "@turnkey/api-key-stamper";
import { TurnkeyClient } from "@turnkey/core";

const stamper = new ApiKeyStamper({
  apiPublicKey: "your-public-key",
  apiPrivateKey: "your-private-key",
});

const client = new TurnkeyClient(
  { organizationId: "your-org-id" },
  stamper, // apiKeyStamper
);