Adding social login to your website with SuperTokens (custom UI only)

This tutorial walks you through integrating your frontend with social login APIs provided by SuperTokens.

Note, that it’s only meant for users who are building their own frontend and are building a website. If you are using our pre built UI, these API integrations are already done for you.

To start off, you want to make sure that you have finished the frontend and backend quick setup guides for the recipe that you have chosen. As of this writing, that’s either:

After finishing the quick setup guides, you should have:

Now we can see how to integrate your frontend UI to work with the backend social auth APIs exposed by SuperTokens.

For ease of explanation, we will assume the following:

We want to implement sign in with GitHub

On a high level, there are two steps to the flow:

Step 1

When the user clicks on Sign in with GitHub button, you want to make the following API call:

const response = await fetch("http://localhost:3001/auth/authorisationurl?thirdPartyId=github",
method: "GET",
headers: {
rid: "thirdpartyemailpassword"

A successful response will look something like:

"status": "OK",
"url": ""

Couple of pointers:

The URL returned in the response is where you will redirect your user to. Before doing that though, you will need to append a query param called redirect_uri to this url whose value should be the callback URL you configured on the GitHub dashboard. We assume that this URL is http://localhost:3000/auth/callback/github.

let urlObj = new URL(response.url)

urlObj.searchParams.append("redirect_uri", "http://localhost:3000/auth/callback/github");let url = urlObj.toString();

The value of url after the above operation will be:

As you can see, we have appended the redirect_uri query param successfully. Now we can redirect the user to this URL.

Step 2

When the user is navigated back to your app (from GitHub), the URL will contain a code query param (on successful login), like this:


First, you need to extract this code in the following way:

let code = new URL(window.location.href).searchParams.get('code');

Then, you need to call another API exposed by the SuperTokens backend SDK to complete the login operation:

const response = await fetch("http://localhost:3001/auth/signinup", {
method: "POST",
headers: {
"rid": "thirdpartyemailpassword",
"Content-Type": "application/json"
body: JSON.stringify({
redirectURI: "http://localhost:3000/callback/github",
thirdPartyId: "github"

Successful execution will result in a response that looks something like:

"status": "OK",
"user": {
"id": "fa7a0841-b533-4478-95533-0fde890c3483",
"email": ""
"createdNewUser": true

A few important points:

Where are the session tokens?

From inspecting the response from the /signinup API call, we don’t see an access token / JWT in the body - so where are they? SuperTokens issues session cookies that get sent via the Set-Cookie header in the response and is automatically handled by the browser.

Furthermore, our frontend SDK handles these session tokens for you automatically:

These features are a part of the session recipe that you initialized when following the quick setup guide.


We have seen how to integrate your custom UI with the social login API exposed by SuperToken’s backend SDK. It involves calling the GET /authorisationurl and the POST /signinup API. Furthermore, we see that on successful login, we are issued cookie-based session tokens which are handled automatically via our frontend SDK.

In case you have any questions please join our discord server.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store