Overview
This guide explains how to set up authentication in your frontend JavaScript application using your backend server in conjunction with the@turnkey/core
. This approach is useful if you do not want to use Turnkey’s auth proxy or are migrating from a previous version of the SDK and already have an existing backend auth setup.
What you can’t use
When implementing backend authentication, you cannot use any authentication helper methods from theTurnkeyClient
, such as completeOtp
, or completeOauth
. These methods are designed to work with Turnkey’s auth proxy and will not function with a custom backend authentication flow.
On your backend
You will need to implement various authentication endpoints on your backend server to forward authentication requests to Turnkey. You’ll need to implement some or all of the following endpoints depending on your authentication flow:createSubOrganization
: Create a new sub-organization for the user.initOtp
: Send an OTP authentication code.verifyOtp
: Verify the OTP code entered by the user.otpLogin
: Handle OTP login flow (you can also combine this withverifyOtp
to make a single endpoint).oauthLogin
: Handle OAuth login flow.
stampLogin
, so you do not need to implement any additional endpoints for those. Signup however will still require the createSubOrganization
endpoint to create a new sub-organization for the user. See the implementation in @turnkey/core
for more details on how to implement loginWithPasskey
and loginWithWallet
using the stampLogin
activity.
Here’s an example of how you might implement the createSubOrganization
endpoint in Node.js using Express and the @turnkey/sdk-server
package:
On your frontend
On the frontend, you will need to implement your own authentication flows that interact with your backend endpoints.Creating a keypair
Login endpoints likeotpLogin
and oauthLogin
will require a public key to be passed in the request.
You can use createApiKeyPair
from the TurnkeyClient
to generate a keypair for this purpose.
createApiKeyPair
will be automatically stored in indexedDB on web environments or secure storage on React Native and used for stamping requests to Turnkey after authentication. You can learn more about stamps here.
Storing the session
Login endpoints likeotpLogin
and oauthLogin
will return a session token in JWT format that you need to store in your application. You can use the storeSession
function from the TurnkeyClient
to store the session token.
@turnkey/core
as usual.