JavaScript Server

Overview

The @turnkey/sdk-server package exposes functionality that lets developers build server-side functionality for applications that interact with the Turnkey API. It exposes a ready-made API client class which manages the process of constructing requests to the Turnkey API and authenticating them with a valid API key. Furthermore, it exposes API proxies that forward requests from your application's client that need to be signed by parent organizations API key.

Use the @turnkey/sdk-server package to handle server-side interactions for applications that interact with the Turnkey API.

Installation

NPM

npm install @turnkey/sdk-server

Yarn

yarn add @turnkey/sdk-server

Initializing

import { Turnkey } from "@turnkey/sdk-server";

const turnkey = new Turnkey({
  defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
  apiBaseUrl: "https://api.turnkey.com",
  apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY,
  apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY,
});

Parameters

configTurnkeySDKServerConfigrequired

An object containing configuration settings for the Server 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)

apiPrivateKeystring

The API Private Key to sign requests with (this will normally be the API Private Key to your root organization)

apiPublicKeystring

The API Public Key associated with the configured API Private Key above

Creating Clients

Calls to Turnkey's API must be signed with a valid credential (often referred to in the docs as stamping) from the user initiating the API call. When using the Server SDK, the user initiating the API call is normally your root organization, and the API call is authenticated with the API keypair you create on the Turnkey dashboard.

apiClient()

The apiClient method returns an instance of the TurnkeyApiClient which will sign requests with the injected apiPrivateKey, and apiPublicKey credentials.

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

// this will sign the request with the configured api credentials

Creating API Proxies

There are certain actions that are initiated by users, but require the activity to be signed by the root organization itself. Examples of this include the initial creation of the user subOrganization or sending an email to a user with a login credential as part of an emailAuth flow.

These can be implemented in your backend by creating an apiClient and handling requests from your browser application at different routes, but we have also provided a convenience method for doing this by having allowing a single apiProxy to handle requests at a single route and automatically sign specific user actions with the root organization's credentials.

expressProxyHandler()

The expressProxyHandler() method creates a proxy handler designed as a middleware for Express applications. It provides an API endpoint that forwards requests to the Turnkey API server.

const turnkeyProxyHandler = turnkey.expressProxyHandler({
  allowedMethods: ["createSubOrganization", "emailAuth", "getSubOrgIds"],
});

app.post("/apiProxy", turnkeyProxyHandler);

// this will sign requests made with the client-side `serverSign` function with the root organization's API key for the allowedMethods in the config

2. nextProxyHandler() [WIP]

The nextProxyHandler() method creates a proxy handler designed as a middleware for Next.js applications. It provides an API endpoint that forwards requests to the Turnkey API server.

// Configure the Next.js handler with allowed methods
const turnkeyProxyHandler = turnkey.nextProxyHandler({
  allowedMethods: ["createSubOrganization", "emailAuth", "getSubOrgIds"],
});

export default turnkeyProxyHandler;

// this will sign requests made with the client-side `serverSign` function with the root organization's API key for the allowedMethods in the config

TurnkeyServerClient

The @turnkey/sdk-server exposes NextJS Server Actions. These server actions can be used to facilitate implementing common authentication flows.

sendOtp()

Initiate an OTP authentication flow for either an EMAIL or SMS

import { server } from "@turnkey/sdk-server";

const initAuthResponse = await server.sendOtp({
  suborgID: suborgId!,
  otpType,
  contact: value,
  ...(emailCustomization && { emailCustomization }),
  ...(sendFromEmailAddress && { sendFromEmailAddress }),
  ...(customSmsMessage && { customSmsMessage }),
  userIdentifier: authIframeClient?.iframePublicKey!,
});

if (initAuthResponse && initAuthResponse.otpId) {
  // proceed to verifyOtp
} else {
  // error handling
}

Parameters

requestSendOtpRequestrequired

An object containing the parameters to initiate an EMAIL or SMS OTP authentication flow.

suborgIDstringrequired

The ID of the sub organization for the given request

otpTypestringrequired

The type of OTP request, either EMAIL or SMS

contactstringrequired

The contact

customSmsMessagestring

Use to customize the SMS message

userIdentifierstring

IP Address, iframePublicKey, or other unique identifier used for rate limiting

verifyOtp()

Verify the OTP Code sent to the user via EMAIL or SMS. If verification is successful, a Session is returned which is used to log in with.

import { server } from "@turnkey/sdk-server";

const authSession = await server.verifyOtp({
  suborgID: suborgId,
  otpId,
  otpCode: otp,
  targetPublicKey: authIframeClient!.iframePublicKey!,
  sessionLengthSeconds,
});

if (authSession?.token) {
  // log in with Session
  await authIframeClient!.loginWithSession(authSession);
  // call onValidateSuccess callback
  await onValidateSuccess();
} else {
  // error handling
}

Parameters

requestVerifyOtpRequestrequired

An object containing the parameters to verify an OTP authentication attempt.

suborgIDstringrequired

The ID of the sub organization for the given request

otpIdstringrequired

The ID for the given OTP request. This ID is returned in the SendOtpResponse from sendOtp()

otpCodestringrequired

The OTP Code sent to the user

targetPublicKeystringrequired

The public key of the target user.

sessionLengthSecondsnumber

Specify the length of the session in seconds. Defaults to 900 seconds or 15 minutes.

oauth()

Complete an OAuth authentication flow once the OIDC Token has been obtain from the OAuth provider.

import { server } from "@turnkey/sdk-server";

const oauthSession = await server.oauth({
  suborgID: suborgId!,
  oidcToken: credential,
  targetPublicKey: authIframeClient?.iframePublicKey!,
  sessionLengthSeconds: authConfig.sessionLengthSeconds,
});

if (oauthSession && oauthSession.token) {
  // log in with Session
  await authIframeClient!.loginWithSession(oauthSession);
  // call onAuthSuccess callback
  await onAuthSuccess();
} else {
  // error handling
}

Parameters

requestOauthRequestrequired

An object containing the parameters to complete an OAuth authentication flow.

suborgIDstringrequired

The ID of the sub organization for the given request

oidcTokenstringrequired

The OIDC (OpenID Connect) Token issued by the OAuth provider which contains basic profile information about the user.

targetPublicKeystringrequired

The public key of the target user.

sessionLengthSecondsnumber

Specify the length of the session in seconds. Defaults to 900 seconds or 15 minutes.

sendCredential()

import { server } from "@turnkey/sdk-server";

const sendCredentialResponse = await server.sendCredential({
  email,
  targetPublicKey: authIframeClient?.iframePublicKey!,
  organizationId: suborgId!,
  ...(apiKeyName && { apiKeyName }),
  ...(sendFromEmailAddress && { sendFromEmailAddress }),
  ...(sessionLengthSeconds && { sessionLengthSeconds }),
  ...(invalidateExisting && { invalidateExisting }),
  ...(emailCustomization && { emailCustomization }),
  ...(sendFromEmailAddress && { sendFromEmailAddress }),
});

Parameters

requestInitEmailAuthRequestrequired

An object containing the parameters to verify an OTP authentication attempt.

suborgIDstringrequired

The ID of the sub organization for the given request

emailstringrequired

The email address provided by the user

targetPublicKeystringrequired

The public key of the target user.

apiKeyNamestring

The name of the API Key

userIdentifierstring

IP Address, iframePublicKey, or other unique identifier used for rate limiting

sessionLengthSecondsnumber

Specify the length of the session in seconds. Defaults to 900 seconds or 15 minutes.

invalidateExistingboolean

Invalidate all pre-existing sessions. Defaults to false.

emailCustomizationEmailCustomization

An optional to customize the email.

sendFromEmailAddressstring

Provide a custom email address which will be used as the sender of the email.