> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-9-digit-updates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedded Wallets Quickstart
> Turnkey's Embedded Wallets enable you to integrate secure, custom wallet experiences directly into your product. With features like advanced security, seamless authentication, and flexible UX options, you can focus on building great products while we handle the complexities of private key management.
## Prerequisites
This guide assumes you've completed the steps to create an account, organization, and API keypair as described in the [Quickstart](/getting-started/quickstart) section.
## Installation
Create a new Next.js app via `npx create-next-app@latest`. Or install into an existing project.
```bash npm theme={"system"}
npm install @turnkey/sdk-react
```
```bash pnpm theme={"system"}
pnpm add @turnkey/sdk-react
```
```bash yarn theme={"system"}
yarn add @turnkey/sdk-react
```
**Technical Requirements**
**Next.js App Router Required**
`@turnkey/sdk-react` requires the Next.js App Router architecture as it leverages React Server Components and Server Actions to handle authentication on your behalf. The SDK automatically manages the "use client" and "use server" directives. The Pages Router is not supported.
**React 19 Users**
If you're using Next.js 15 with React 19 you may encounter an installation error with `@turnkey/sdk-react`. Consider:
* Downgrading React to `18.x.x`
* Using `npm install --force` or `--legacy-peer-deps`
You may learn more about this [here](https://ui.shadcn.com/docs/react-19).
## Setup
The following environment variables are necessary to use the Turnkey SDK.
```bash .env theme={"system"}
NEXT_PUBLIC_ORGANIZATION_ID=
TURNKEY_API_PUBLIC_KEY=
TURNKEY_API_PRIVATE_KEY=
NEXT_PUBLIC_BASE_URL=https://api.turnkey.com
```
**Note**: These environment variable names must be used exactly as shown.
The SDK depends on them internally for server actions and authentication.
Fill in with your Organization ID and API Base URL.
```tsx src/app/layout.tsx theme={"system"}
const config = {
apiBaseUrl: "https://api.turnkey.com",
defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID,
};
```
Wrap your layout with the `TurnkeyProvider` component, and import styles from sdk-react.
```tsx src/app/layout.tsx theme={"system"}
import { TurnkeyProvider } from "@turnkey/sdk-react";
import "@turnkey/sdk-react/styles"; // required to render auth component styles properly
export default function RootLayout({ children }) {
return (
{children}
);
}
```
**React 19 Users**
`@turnkey/sdk-react` is built with React 18. If you're using React 19 you'll find a type mismatch on the children type.
To fix this, you can use the `@ts-ignore` directive to suppress the error.
src/app/layout.tsx
```
{/* @ts-ignore */} {children}
```
We're actively working towards React 19 compatibility.
## Authenticate
The auth component contains the UI and logic to handle the authentication flow.
For simplicity, this app will only support email authentication. We have other guides on additional authentication methods. Additionally, you can customize the order in which the auth methods are displayed.
```tsx src/app/page.tsx theme={"system"}
"use client";
export default function Home() {
// The auth methods to display in the UI
const config = {
authConfig: {
emailEnabled: true,
// Set the rest to false to disable them
passkeyEnabled: false,
phoneEnabled: false,
appleEnabled: false,
facebookEnabled: false,
googleEnabled: false,
},
// The order of the auth methods to display in the UI
configOrder: ["email" /* "passkey", "phone", "socials" */],
};
return ;
}
```
```
type AuthConfig = {
emailEnabled: boolean;
passkeyEnabled: boolean;
phoneEnabled: boolean;
appleEnabled: boolean;
googleEnabled: boolean;
facebookEnabled: boolean;
};
```
Import the auth component into your app and pass in the config object.
```tsx src/app/page.tsx theme={"system"}
"use client";
import { Auth } from "@turnkey/sdk-react";
export default function Home() {
const config = {
authConfig: {
emailEnabled: true,
passkeyEnabled: false,
phoneEnabled: false,
appleEnabled: false,
facebookEnabled: false,
googleEnabled: false,
},
configOrder: ["email"],
};
return (
);
}
```
Define two functions to handle the "success" and "error" states. Initially, the `onError` function will set an `errorMessage` state variable which will be used to display an error message to the user. The `onAuthSuccess` function will route the user to the dashboard after successful authentication.
A new [sub-organization](/concepts/sub-organizations) and [wallet](/concepts/wallets) is created for each new user during the authentication flow.
```tsx src/app/page.tsx theme={"system"}
"use client";
import { useState } from "react";
import { Auth } from "@turnkey/sdk-react";
export default function Home() {
const [errorMessage, setErrorMessage] = useState("");
const router = useRouter();
const onAuthSuccess = async () => {
// We'll add the dashboard route in the next step
router.push("/dashboard");
};
const onError = (errorMessage: string) => {
setErrorMessage(errorMessage);
};
// Add the handlers to the config object
const config = {
// ...
onAuthSuccess: onAuthSuccess,
onError: onError,
};
return (
);
}
```
Add a dashboard route to the app where the user will be able to view their account and sign messages.
```tsx src/app/dashboard/page.tsx theme={"system"}
export default function Dashboard() {
return
Dashboard
;
}
```
Since the app is wrapped with the `TurnkeyProvider` component, the `useTurnkey` hook is available to all child components. Calling `turnkey.getCurrentUser()` will return the current user's session information from local storage.
Add a state variable to store the user:
```tsx src/app/dashboard/page.tsx theme={"system"}
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
export default function Dashboard() {
const { turnkey } = useTurnkey();
const [user, setUser] = useState(null);
useEffect(() => {
if (turnkey) {
const user = turnkey.getCurrentUser();
setUser(user);
}
}, [turnkey]);
return
Dashboard
;
}
```
```
export interface User {
// Unique identifier for the user.
userId: string;
// Username of the user.
username: string;
organization: {
// Unique identifier for the organization.
organizationId: string;
// Name of the organization.
organizationName: string;
};
session:
| {
// read-only session .
read?: ReadOnlySession;
// read-write session details.
write?: ReadWriteSession;
// Authenticated client associated with the session.
authClient: AuthClient;
}
| undefined;
}
export interface ReadOnlySession {
// Read-only session token for `X-Session` header
token: string;
// Expiry time in seconds since Unix epoch.
expiry: number;
}
export interface ReadWriteSession {
// Credential bundle for iFrame client, generated by `createReadWriteSession` or `createApiKeys`.
credentialBundle: string;
// Expiry time in seconds since Unix epoch.
expiry: number;
}
```
## Sign Message
Turnkey supports signing arbitrary messages with the [`signRawPayload`](/api-reference/signing/sign-raw-payload) method.
The `signRawPayload` method requires these parameters:
* `payload`: The raw unsigned payload to sign
* `signWith`: The signing address (wallet account, private key address, or private key ID)
* `encoding`: The message encoding format
* `hashFunction`: The selected hash algorithm
For simplicity, a human readable string, `message`, will be the payload to sign. Add a state variable to store the message and an input field to allow the user to enter the message:
```tsx src/app/dashboard/page.tsx theme={"system"}
import { useState, useEffect } from "react";
export default function Dashboard() {
//...
const [message, setMessage] = useState("");
//...
return (
setMessage(e.target.value)}
placeholder="Enter message to sign"
/>
);
}
```
Signing messages requires a signer e.g. a Turnkey wallet address to sign with and a payload or message to sign. A new wallet is created for each user during the authentication flow.
Create a function called `getSignWith`, to get the user's wallet account address which will be used to sign the message.
Use the `getActiveClient` method from the `useTurnkey` hook to get the client authenticated with the user's read-write session:
```tsx src/app/dashboard/page.tsx theme={"system"}
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
export default function Dashboard() {
const { turnkey, getActiveClient } = useTurnkey();
const [user, setUser] = useState(null);
const getSignWith = async () => {
// This will return the authIframeClient with the credential bundle injected
const client = await getActiveClient();
// The user's sub-organization id
const organizationId = user?.organization.organizationId;
// Get the user's wallets
const wallets = await client?.getWallets({
organizationId,
});
// Get the first wallet of the user
const walletId = wallets?.wallets[0].walletId ?? "";
// Use the `walletId` to get the accounts associated with the wallet
const accounts = await client?.getWalletAccounts({
organizationId,
walletId,
});
const signWith = accounts?.accounts[0].address ?? "";
return signWith;
};
useEffect(/* ... */*/);
return (/*
...
*/*/);
}
```
Create a function called `signMessage`. This function will:
* Get the user's wallet account for signing the message
* Compute the keccak256 hash of the message
* Call the `signRawPayload` method
Note: To compute the `keccak256` hash of the message, this example uses the `hashMessage` function from `viem`. However, any other hashing library can be used.
```tsx theme={"system"}
const signMessage = async () => {
const payload = await hashMessage(message);
const signWith = await getSignWith();
const signature = await client?.signRawPayload({
payload,
signWith,
// The message encoding format
encoding: "PAYLOAD_ENCODING_TEXT_UTF8",
// The hash function used to hash the message
hashFunction: "HASH_FUNCTION_KECCAK256",
});
};
```
Add a button to the UI to trigger the `signMessage` function.
```tsx src/app/dashboard/page.tsx theme={"system"}
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
import { hashMessage } from "viem";
export default function Dashboard() {
//...
const [message, setMessage] = useState("");
const signMessage = async () => {
const payload = await hashMessage(message);
const signWith = await getSignWith();
const signature = await client?.signRawPayload({
payload,
signWith,
// The message encoding format
encoding: "PAYLOAD_ENCODING_TEXT_UTF8",
// The hash function used to hash the message
hashFunction: "HASH_FUNCTION_KECCAK256",
});
};
return (
Sign Message
setMessage(e.target.value)}
placeholder="Enter message to sign"
/>
);
}
```
## Recap
In this quickstart guide, you've learned how to:
1. Set up Turnkey's SDK in a Next.js application
2. Configure authentication with email sign-in
3. Create a protected dashboard route
4. Implement message signing functionality using a user's Turnkey wallet
5. Handle user sessions and wallet interactions
```tsx src/app/page.tsx theme={"system"}
"use client";
import { useState } from "react";
import { Auth } from "@turnkey/sdk-react";
export default function Home() {
const [errorMessage, setErrorMessage] = useState("");
const router = useRouter();
const onAuthSuccess = async () => {
router.push("/dashboard");
};
const onError = (errorMessage: string) => {
setErrorMessage(errorMessage);
};
const config = {
authConfig: {
emailEnabled: true,
passkeyEnabled: false,
phoneEnabled: false,
appleEnabled: false,
facebookEnabled: false,
googleEnabled: false,
},
configOrder: ["email"],
onAuthSuccess: onAuthSuccess,
onError: onError,
};
return (
The auth component contains the UI and logic to handle the authentication flow.