Reference

Find SuperTokens backend SDK references and customize authentication functions, APIs, and configuration.

Overview

SuperTokens has support for Node.js, Python, and Golang through its backend SDKs. Use this page to find references to each of them and about specific functionalities.

SDKs

SDK configuration

The appInfo object is the parameter used to configure the SDKs during initialization.

let appInfo: {
  appName: string;
  apiDomain: string;
  websiteDomain?: string;
  websiteBasePath?: string;
  origin?: ((input: { request?: Request; userContext: UserContext }) => string) | string;
  apiBasePath?: string;
  apiGatewayPath?: string;
};

appName

This is the name of your application. Use it when sending password reset or email verification emails (in the default email design). An example of this is appName: "GitHub".

websiteDomain

This is the domain part of your website. This is where the login UI appears. For example:

For local development, you are likely using localhost with some port (ex 8080). Then the value of this should be "http://localhost:8080".
If your website is https://www.example.com, then the value of this should be "https://www.example.com".
If your website is https://example.com, then the value of this should be "https://example.com".
If you have multiple sub domains, and your users login via https://auth.example.com, then the value of this should be "https://auth.example.com".

By default, the login UI appears on {websiteDomain}/auth/*. You can change this by using the websiteBasePath configuration.

On the frontend, you need the domain for routing purposes, and on the backend, it generates correct email verification and password reset links.

apiDomain

This is the domain part of your API endpoint that the frontend talks to. For example:

For local development, you are likely using localhost with some port (ex 9000). Then the value of this should be "http://localhost:9000".
If your frontend queries https://api.example.com/*, then the value of this should be "https://api.example.com"
If your API endpoint reaches /api/*, then the value of this is the same as the websiteDomain - since /api/* is equal to querying {websiteDomain}/api/*.

By default, the login widgets query {apiDomain}/auth/*. You can change this by using the apiBasePath configuration.

websiteBasePath

By default, the login UI appears on {websiteDomain}/auth. Other authentication-related user interfaces appear on {websiteDomain}/auth/*.

If you want to change the /auth to something else, then you must set this value. For example:

If you want the login UI to show on {websiteDomain}/user/*, then the value of this should be "/user".
If you are using a dedicated sub domain for auth, like https://auth.example.com, then you probably want the login UI to show up on https://auth.example.com. In this case, set this value to "/".

origin

Can be used instead of websiteDomain to handle multiple frontend domains within the same SuperTokens instance. The property accepts a function that receives the original request as an input and should return a valid domain. Make sure to whitelist all the domains during CORS configuration.

apiBasePath

By default, the frontend SDK queries {apiDomain}/auth/*.

If you want to change the /auth to something else, then you must set this value. For example:

If you have versioning in your API path and want to query {apiDomain}/v0/auth/*, then the value of this should be "/v0/auth".
If you want to scope the APIs not via /auth but via some other string like /supertokens, then you can set the value of this to "/supertokens". This means, the APIs appear on {apiDomain}/supertokens/*.
If you do not want to scope the APIs at all, then you can set the values of this to be "/". This means the APIs are available on {apiDomain}/*

apiGatewayPath

If you are using an API gateway (like the one provided by AWS) or a reverse proxy (like Nginx), it may add a path to your API endpoints to scope them for different development environments. For example, your APIs for development appear via {apiDomain}/dev/*, and for production, they may appear via {apiDomain}/prod/*.

Whilst the frontend would need to use the /dev/ and /prod/, your backend code would not see that sub path (that is /dev/ and /prod/ because the gateway removes them).

For these situations, you should set the apiGatewayPath to /dev or /prod. For example:

If your API gateway is using /development for scoping, and you want to expose the SuperTokens APIs on /supertokens/*, then set apiGatewayPath: "/development" & apiBasePath: "/supertokens". This means that the frontend SDK queries {apiDomain}/development/supertokens/* to reach the endpoints exposed by the service.
If you set this and not apiBasePath, then the frontend SDK queries {apiDomain}{apiGatewayPath}/auth/* to reach the endpoints exposed by the service.

The reason for this distinction between apiGatewayPath and apiBasePath is that when routing, the backend SDK does not see the apiGatewayPath path from the request because the gateway removes them. Taking the above example, whilst the frontend queries {apiDomain}/development/supertokens/*, the backend SDK sees {apiDomain}/supertokens/*.

Reference

Overview

Customization

SDKs

Node.js

Go

Python

SDK configuration

API schema and response details