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
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)
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 usersubOrganization 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()
TheexpressProxyHandler() 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()
ThenextProxyHandler() 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.verifyOtp()
Verify the OTP Code sent to the user via EMAIL or SMS.
Parameters
An object containing the parameters to verify an OTP authentication attempt.
createOauthSession()
Complete an OAuth authentication flow after obtaining an OIDC token from the OAuth provider. This
creates a Turnkey session bound to the provided public key.
Parameters
An object containing the parameters to create a Turnkey session via OIDC.
sendCredential()
Send a login credential to a user’s email address.
Parameters
An object containing the parameters to send a login credential via email.