Skip to main content

Javascript Browser

Installation​

yarn add @turnkey/sdk-browser

Initializing​

import { Turnkey } from "@turnkey/sdk-browser";
import turnkeyConfig from "./turnkey.json"
const turnkey = new Turnkey(turnkeyConfig);

Parameters​

An object containing configuration settings for the Browser Client.

defaultOrganizationIdstringrequired

The root organization that requests will be made from unless otherwise specified

apiBaseUrlstringrequired

The base URL that API requests will be sent to (use https://api.turnkey.com when making requests to Turnkey's API)

rpIdstring

The Relying Party ID used for WebAuthn flows (will default to the value returned from window.location.hostname unless otherwise specified)

serverSignUrlstring

The URL to send requests that need to be signed from a backend codebase by the root organization's API key if using the serverSign flow.

Turnkey Clients​

Calls to Turnkey's API must be signed with a valid credential from the user initiating the API call. This can take multiple different forms depending on the kind of authentication credential that is being used.

1. Passkey Client​

The passkey client will prompt a user to sign with a passkey credential to authenticate the API call.

const passkeyClient = turnkey.passkeyClient();
const walletsResponse = await passkeyClient.getWallets();

// this requires the user to authenticate with a passkey credential in their browser

2. Iframe Client​

The Iframe client is used to interact with a series of iframes hosted by Turnkey, designed for sensitive operations such as storing an expiring credential within the Email Recovery and Email Auth flows, and facilitating Wallet Import and Export. The code powering these iframes can be found at https://github.com/tkhq/frames.

const iframeClient = await turnkey.iframeClient({
  iframeContainer: document.getElementById("<iframe container id>"),
  iframeUrl: "https://auth.turnkey.com"
});
const response = await iframeClient.injectCredentialBundle("<Credential from Email>");
if (response) { await iframeClient.getWallets(); }

// this requires the developer to build a wrapper flow that can take user text input in their app and call the injectCredentialBundle function on the turnkey iframeClient

3. Read-only User Session Client​

Generally speaking, in order to ensure a seamless UX, you might not want a passkey user have to manually authenticate every read request from Turnkey's API with a credential (e.g. via FaceID or TouchID). In order to reduce friction, you can have a user login() to Turnkey with a credential once, resulting in a session that allows multiple read-only requests to Turnkey's API via userSessionClient.

const passkeyClient = turnkey.passkeyClient();
await passkeySigner.login();

// when a user logs in with the Turnkey SDK, a read-only API credential is saved in localStorage and can be used to make API read requests on their behalf

const userSessionClient = await turnkey.currentUserSession();
const walletsResponse = await userSessionClient.getWallets();

// this API call happens without any confirmation step because the user now has an active read-only session

4. Server Signer​

The serverSign function is used to proxy requests from a root parent organization to a child organization. The API key cannot be stored client-side, which is why the serverSign flow exists: to forward authenticated client-side requests to Turnkey via proxy backend.

const subOrgIdsResponse = await turnkey.serverSign(
  "getSubOrgIds",
    [{
      filterType: "EMAIL",
      filterValue: email
    }]
  )!

if (subOrgIdsResponse.organizationIds?.length > 0) {
  const emailAuthResponse = await turnkey.serverSign(
    "emailAuth",
    [{
      email: email,
      targetPublicKey: <iframeClient.iframePublicKey>,
      organizationId: subOrgIdsResponse.organizationIds[0]
    }]
  )
}

Examples​

1. Implementing an embedded wallet authentication flow with passkeys​

2. Implementing an embedded wallet authentication flow with email​

3. Signing Transactions​