Core Concepts

Understand key Turnkey SDK concepts

Turnkey’s architecture introduces a small set of primitives that appear throughout the SDK. Understanding them helps you make sense of the API surface and configuration options.

If you are using @turnkey/react-wallet-kit, you do not need to understand most of these internals. The package abstracts them behind the TurnkeyProvider and useTurnkey hook. This page is most useful when you are debugging, building a custom integration, or using lower-level packages directly.

Organizations and sub-organizations

Every Turnkey account belongs to an organization. Your organization is the top-level container that owns your API keys, policies, and configuration.

When a user signs up through your application, Turnkey creates a sub-organization scoped to that user. Sub-organizations are isolated units of ownership: the user controls their own keys and wallet, while your parent organization retains administrative visibility and the ability to sponsor operations.

This model means:

• Your server’s API keys never hold or control user funds.
• Each user’s wallet is owned by their own sub-organization, not your organization.
• You can still apply policies, recover accounts, and perform organizational operations from your parent organization.

The organizationId you pass into TurnkeyProviderConfig is your parent organization ID. The SDK automatically creates and manages sub-organizations per user during authentication.

Wallets and wallet accounts

A wallet in Turnkey is a hierarchical deterministic (HD) wallet. It stores a seed from which any number of addresses can be derived.

A wallet account is a derived address on a specific blockchain, defined by a derivation path and address format. For example, an Ethereum account derived at m/44'/60'/0'/0/0 or a Solana account derived at m/44'/501'/0'/0'.

Key properties:

• One wallet can have accounts on multiple chains simultaneously.
• Accounts are derived deterministically — the same seed always produces the same address.
• Turnkey never exposes the raw private key to your server or the browser. Signing happens inside Turnkey’s secure enclave.

The SDK provides default account constants such as DEFAULT_ETHEREUM_ACCOUNTS and DEFAULT_SOLANA_ACCOUNTS (exported from @turnkey/sdk-server) to use when creating wallets with standard derivation paths.

Stampers

A stamper is the component that authenticates a request to the Turnkey API. Every request to Turnkey must carry a cryptographic stamp — a signature that proves the request came from an authorized credential.

Turnkey supports several stamper types:

Stamper	Use case
API key stamper (@turnkey/api-key-stamper)	Server-side requests signed with a long-lived API key
WebAuthn stamper (@turnkey/webauthn-stamper)	Browser requests signed by a passkey (WebAuthn credential)
Iframe stamper (@turnkey/iframe-stamper)	Requests signed inside a sandboxed iframe, used for import/export flows
Wallet stamper (@turnkey/wallet-stamper)	Requests signed by an external wallet (MetaMask, Phantom, etc.)
IndexedDB stamper (@turnkey/indexed-db-stamper)	Requests signed by an unextractable P-256 key stored in the browser’s IndexedDB

When you use @turnkey/react-wallet-kit or @turnkey/core, stampers are selected and applied automatically based on the active authentication method. You only need to configure stampers directly when using lower-level packages.

Activities

Mutating operations on the Turnkey API — such as creating a wallet, signing a transaction, or creating a sub-organization — are modeled as activities. Activities are asynchronous: you submit an activity, and it transitions through states (PENDING, COMPLETE, FAILED) as Turnkey’s infrastructure processes it.

For most operations, the SDK polls until the activity reaches a terminal state and returns the result. The lower-level @turnkey/http package exports a createActivityPoller helper for cases where you need to poll manually:

import { createActivityPoller } from "@turnkey/http";

Higher-level packages handle polling automatically, so you typically only encounter this concept when building custom flows with @turnkey/http directly.

Auth Proxy

The Auth Proxy is a managed proxy service operated by Turnkey. It allows browser-based applications to make Turnkey API requests without exposing a server-side API key to the client.

Here is how it works:

1. Your application sends a request to Turnkey’s Auth Proxy endpoint.
2. The proxy stamps the request using credentials associated with your Auth Proxy Config, which you configure in the Turnkey dashboard.
3. The stamped request is forwarded to the Turnkey API.

You reference the proxy via the authProxyConfigId field in TurnkeyProviderConfig:

const turnkeyConfig: TurnkeyProviderConfig = {
  organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
  authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID!,
};

Using the Auth Proxy is the recommended approach for React and React Native applications. It means you do not need to run your own backend to proxy Turnkey requests — though the SDK also supports a self-hosted backend proxy if you prefer.

Embedded wallets

An embedded wallet is a non-custodial wallet that lives entirely within the user’s browser or device. Unlike browser extension wallets (MetaMask, Phantom), embedded wallets are created and controlled inside your application’s UX — users never have to install anything or switch contexts.

Turnkey’s embedded wallets work as follows:

• The wallet seed is generated and stored inside Turnkey’s secure enclave.
• Authentication is handled by the method the user chose (passkey, OTP, OAuth, or external wallet).
• Signing happens server-side inside the enclave — private keys never leave Turnkey.
• Users can optionally export their wallet to store it independently.

@turnkey/react-wallet-kit and @turnkey/react-native-wallet-kit are specifically designed for building embedded wallet experiences. The import and export flows (using @turnkey/iframe-stamper under the hood) let users move wallets in and out of Turnkey’s custody if they choose.