JavaScript Server
The @turnkey/sdk-server
package exposes functionality that lets developers build server-side functionality for applications that interact with the Turnkey API.
Overview
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
Initializing
Parameters
An object containing configuration settings for the Server Client.
The root organization that requests will be made from unless otherwise specified
The base URL that API requests will be sent to (use https://api.turnkey.com when making requests to Turnkey’s API)
The API Private Key to sign requests with (this will normally be the API Private Key to your root organization)
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.
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.
2. nextProxyHandler()
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.
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
.
Parameters
An object containing the parameters to initiate an EMAIL
or SMS
OTP
authentication flow.
The ID of the sub organization for the given request.
The type of OTP request, either EMAIL
or SMS
.
The contact information (email or phone number) where the OTP will be sent.
Use to customize the SMS message.
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.
Parameters
An object containing the parameters to verify an OTP authentication attempt.
The ID of the sub organization for the given request.
The ID for the given OTP request. This ID is returned in the SendOtpResponse
from sendOtp()
.
The OTP Code sent to the user.
The public key of the target user.
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 obtained from the OAuth provider.
Parameters
An object containing the parameters to complete an OAuth authentication flow.
The ID of the sub organization for the given request.
The OIDC (OpenID Connect) Token issued by the OAuth provider which contains basic profile information about the user.
The public key of the target user.
Specify the length of the session in seconds. Defaults to 900 seconds or 15 minutes.
sendCredential()
Send a login credential to a user’s email address.
Parameters
An object containing the parameters to send a login credential via email.
The email address provided by the user.
The public key of the target user.
The ID of the sub organization for the given request.
The name of the API Key.
IP Address, iframePublicKey, or other unique identifier used for rate limiting.
Specify the length of the session in seconds. Defaults to 900 seconds or 15 minutes.
Invalidate all pre-existing sessions. Defaults to false
.
An option to customize the email.
Provide a custom email address which will be used as the sender of the email.
Was this page helpful?