@turnkey/sdk-react-native v1.0.1

@turnkey/sdk-react-native

The @turnkey/sdk-react-native package simplifies the integration of the Turnkey API into React Native applications. It provides secure session management, authentication, and cryptographic operations using react-native-keychain, @turnkey/crypto, @turnkey/api-key-stamper, and @turnkey/http.

Installation

• Install the following dependencies in your React Native project:
  • react-native-keychain
  • @turnkey/crypto
  • @turnkey/api-key-stamper
  • @turnkey/http
  • @turnkey/sdk-react-native (this package)
• Ensure your app is properly configured for secure storage and authentication.

• You must polyfill random byte generation to ensure generateP256KeyPair from @turnkey/crypto works properly by importing react-native-get-random-values at the entry point of your application:

  import "react-native-get-random-values";

Usage

Wrapping Your App with the Provider

import { TurnkeyProvider } from "@turnkey/sdk-react-native";
import { useRouter } from "expo-router";
import React from "react";

export const AppProviders = ({ children }: { children: React.ReactNode }) => {
  const router = useRouter();

  const turnkeyConfig = {
    apiBaseUrl: "https://api.turnkey.com",
    organizationId: "<your organization id>",
    onSessionCreated: (session) => {
      console.log("Session Created", session);
    },
    onSessionSelected: (session) => {
      console.log("Session Selected", session);
      router.replace("/dashboard");
    },
    onSessionExpired: (session) => {
      console.log("Session Expired", session);
      router.push("/");
    },
    onSessionCleared: (session) => {
      console.log("Session Cleared", session);
      router.push("/");
    },
  };

  return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>;
};

Session Storage

To enable secure authentication, the following storage keys are used:

• @turnkey/embedded-key: Stores the private key that corresponds to the public key used when initiating the session request to Turnkey.
• @turnkey/session: Default session storage key, storing the session credentials, including the private key, public key, and expiry time, which are decrypted from the credential bundle after a session is created.
• @turnkey/session-keys: Stores the list of stored session keys.
• @turnkey/selected-session: Stores the currently selected session key.

Functions Provided by the Turnkey Provider

Session Management

• createEmbeddedKey(): Generates a new embedded key pair and securely stores the private key.
• createSession({ bundle, expirationSeconds?, sessionKey? }): Creates a session. (API Docs)
  • If sessionKey is provided, the session will be stored under that key in secure storage.
  • If no session exists, the first session created is automatically selected.
  • If a session with the same sessionKey already exists in secure storage, an error is thrown.
• setSelectedSession({ sessionKey }): Selects a session by its key (Used when handling multiple sessions).
• clearSession({ sessionKey? }): Removes the specified session from secure storage. If no sessionKey is provided, the currently selected session is removed.
• clearAllSessions(): Clears all sessions from secure storage.

User Management

• updateUser({ email?, phone? }): Updates the user's email and/or phone number. (API Docs)
• refreshUser(): Fetches the latest user data. (API Docs)

Wallet Management

• createWallet({ walletName, accounts, mnemonicLength? }): Creates a wallet. (API Docs)
• importWallet({ walletName, mnemonic, accounts }): Imports a wallet. (API Docs)
• exportWallet({ walletId }): Exports a wallet mnemonic. (API Docs)

Transaction Signing

• signRawPayload({ signWith, payload, encoding, hashFunction }): Signs a payload. (API Docs)

Handling Multiple Sessions

Most users won't need multiple sessions, but if your app requires switching between multiple sessions, here’s what you need to know:

This SDK supports multiple sessions, allowing you to create and switch between different session keys using setSelectedSession({ sessionKey }). When a session is selected, the client, user, and session information are updated accordingly, so that all subsequent function calls (like updateUser or createWallet) apply to the selected session.

• Creating a Session with a Custom Id: You can pass a sessionKey when calling createSession. If provided, the session will be stored in secure storage under that ID, allowing for multiple sessions.
• Switching Sessions: Use setSelectedSession({ sessionKey }) to switch between stored sessions. The client, user, and session information will automatically update.
• Session Expiry Management: Each session has an expiry time, and expired sessions will be automatically cleared.
• Callbacks for Session Events:
  • onSessionCreated: Called when a session is created.
  • onSessionSelected: Called when a session is selected.
  • onSessionExpired: Called when a session expires.
  • onSessionCleared: Called when a session is cleared.

When are multiple sessions useful?

Using multiple sessions can be beneficial when enabling different authentication methods for various operations. For example, you might authenticate a user with OTP for login while using a passkey-based session for signing transactions.

Demo App

Check out this repository for a full working example.