Wallet Authentication
In this guide, we’ll explore how to leverage the WalletClient
in the Turnkey SDK to authenticate requests to Turnkey’s API using either Solana or Ethereum wallets.
Initialize
Begin by initializing the Turnkey SDK by passing in a config object containing:
apiBaseUrl
: The base URL of the Turnkey API:https://api.turnkey.com
.defaultOrganizationId
: Your parent organization ID, which you can find in the Turnkey dashboard.wallet
: The wallet interface used to sign requests. In this example, we’ll use theEthereumWallet
interface.
First, wrap your application with the TurnkeyProvider
in your app/layout.tsx
file:
Then, create a new page component app/page.tsx
where we’ll implement the wallet authentication functionality:
Sign Up
In this section, we’ll guide you through the process of implementing a sign-up flow using an Ethereum wallet for authentication. The sign-up process involves creating a new sub-organization within your existing organization. This requires authentication of the parent organization using its public/private key pair. Additionally, we’ll cover how to verify if a user already has an associated sub-organization before proceeding.
Server-side
Initialize the Turnkey SDK on the server-side using the @turnkey/sdk-server
package. This setup enables you to authenticate requests to Turnkey’s API using the parent organization’s public/private API key pair. This is required to create new sub-organizations on behalf of a user.
For Next.js, add the "use server"
directive at the top of the file where you’re initializing the Turnkey server client. This will ensure that the function is executed on the server-side and will have access to the server-side environment variables e.g. your parent organization’s public/private API key pair. For more information on Next.js server actions, see the Next.js documentation on Server Actions and Mutations.
Check for Existing User
Before signing up a new user, we can try and retrieve the user’s sub-organization ID using the public key associated with the Ethereum or Solana account they want to authenticate with. If a sub-organization is found, we can proceed with authentication; otherwise, we assume the user is signing up.
We’ll use the getPublicKey
method on the WalletClient
instance which will retrieve the public key from the user’s wallet.
The main distinction between signing with an Ethereum Wallet and a Solana Wallet lies in how the public key is obtained. For Solana, the public key can be directly derived from the wallet. In contrast, with Ethereum, the secp256k1 public key isn’t directly accessible. Instead, you need to first obtain a signature from the user and then recover the public key from that signature. This requires an additional step of signing a message with the user’s Ethereum wallet before we can retrieve the public key.
We’ll define this function in the server-side code we initialized earlier.
Next, we’ll add the client-side functionality to the app/page.tsx
file we created earlier importing the getSubOrg
function we defined in our server action.
Create Sub-Organization
Next, we’ll define a method to create a sub-organization for new user sign-ups.
For more information, refer to the Sub-Organizations guide.
We’ll define another server action createSubOrg
to create a sub-organization for new user sign-ups.
Then, we’ll import and use this createSubOrg
function within the login method. The curve type is set to API_KEY_CURVE_SECP256K1
since we’re using an Ethereum wallet in this example.
Sign In
At this point, we have a working sign-up flow. Next, we’ll implement the signing in functionality by creating a read-only session and retrieving the user’s wallets.
Read-only Session
Create a read-only session for the user by calling the login
method on the WalletClient
instance. This will save a read-only session token to the localStorage
to authenticate future read requests.
Retrieve Wallets
Once the user is authenticated, we can retrieve the user’s wallets by calling the getWallets
method on the WalletClient
instance.
Read-write Session
It is also possible to create a read-write session for the user by calling the loginWithReadWriteSession
method on the WalletClient
instance. This will save a read-write session token to the localStorage
to authenticate future read/write requests. This session can be used with the TurnkeyIframeClient
to make read/write requests to the Turnkey API.
Most of the code is the same as the read-only session example. The only difference is that we replace login
with loginWithReadWriteSession
and use the getActiveClient
method to get the IframeClient
instance and using it to create a new wallet.
Define a new function addWallet
which will create a new wallet using the read-write client. We’ll also add a button to trigger this function.
Examples
You can find examples of how to implement the above functionality and more in the following repositories: