Getting Started with @turnkey/core

Turnkey organization setup

To start, you must create a Turnkey organization via the Turnkey dashboard. The steps are described in the Account Setup section. For this setup, we will use Turnkey’s Auth Proxy to handle authentication. You can enable and configure this through the Turnkey dashboard.

Enable auth proxy

Navigate to the Auth section in the Turnkey dashboard and enable the Auth Proxy.

Customize auth methods

You can choose which auth methods to enable and customize various options from this screen. For this quickstart, let’s enable email OTP. When you’re done, click Save.

Finish up

Once you’re finished with the auth proxy setup, copy your Auth Proxy Config ID and your Organization ID from the dashboard.

These values will be required to configure the SDK in your app.

Installation

Install the Turnkey Core SDK into your project:

npm install @turnkey/core

pnpm add @turnkey/core

yarn add @turnkey/core

React Native setup

If you’re using React Native, there’s some additional setup required. You can skip this section if you’re using a web framework.

Install peer dependencies

Install the following peer dependencies.

npm install @react-native-async-storage/async-storage react-native-keychain @turnkey/react-native-passkey-stamper

pnpm add @react-native-async-storage/async-storage react-native-keychain @turnkey/react-native-passkey-stamper

yarn add @react-native-async-storage/async-storage react-native-keychain @turnkey/react-native-passkey-stamper

If you’re not using Expo, you may need to install the iOS dependencies.

npx pod-install
# or
cd ios && pod install

Configure required polyfill

@turnkey/core requires a polyfill to work in React Native.Install the react-native-get-random-values package.

npm install react-native-get-random-values

pnpm add react-native-get-random-values

yarn add react-native-get-random-values

Then, import it at the top of your entry file (e.g. index.js, entry.js etc.). If you don’t have this file, you’ll need to create one.

index.js

import 'react-native-get-random-values';
// ... other imports

// You may need this line if you're using Expo Router
import 'expo-router/entry';

You’ll need to add this file to your package.json under the main field if it’s not already there.

package.json

{
  "main": "index.js", // May be named differently in your project
  // ... other fields
}

Client initialization

Unlike @turnkey/react-wallet-kit, @turnkey/core doesn’t provide a React provider or hooks — you work directly with the TurnkeyClient. Here’s a minimal setup example:

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

const client = new TurnkeyClient({
  organizationId: "YOUR_ORGANIZATION_ID",
  authProxyConfigId: "YOUR_AUTH_PROXY_CONFIG_ID", // Can be omitted if you don't use the Auth Proxy
});

// Initialize the client. Required for async initialization.
await client.init();

Optional configuration

The client accepts optional configuration for passkeys and external browser wallets. If omitted, those features will not be initialized.

Passkeys

const client = new TurnkeyClient({
  organizationId: "...",
  authProxyConfigId: "...",
  passkeyConfig: {
    rpId: "example.com", // Required for React Native
    timeout: 60000, // Default: 5 minutes
    userVerification: "preferred",
  },
});

All fields are optional in web environments. On React Native, rpId is required. We recommend following this guide to set up associated domains for iOS and Android.

External browser wallets

const client = new TurnkeyClient({
  organizationId: "...",
  authProxyConfigId: "...",
  walletConfig: {
    chains: {
      ethereum: {
        native: true,
        walletConnectNamespaces: ["eip155:1"], // Ethereum mainnet
      },
      solana: {
        native: true,
        walletConnectNamespaces: ["solana:mainnet"],
      },
    },

    // Optional: Configure WalletConnect. WalletConnect is used for connecting wallets from mobile devices.
    walletConnect: {
      projectId: "YOUR_PROJECT_ID",
      appMetadata: {
        name: "My App",
        description: "My dApp powered by Turnkey",
        url: "https://example.com",
        icons: ["https://example.com/icon.png"],
      },
    },
  },
});

​Turnkey organization setup

​Installation

​React Native setup

​Client initialization

​Optional configuration

​Passkeys

​External browser wallets