Skip to content
SuperTokens Docs
Esc
↑↓navigate↵open⌘Jpreview
Dashboard
On this page

Reference

Override frontend authentication functions using SuperTokens for custom session and user sign-up logic.

Overview

SuperTokens exposes SDKs for frontend frameworks. Use this page to find references to each of them and about specific functionalities.

Customization

Function overrides

Hooks

Component override

Prebuilt UI styling

Prebuilt UI theming

Translations

SDKs

React

supertokens/supertokens-auth-reactReactJS authentication module for SuperTokens30696

JavaScript

supertokens/supertokens-web-jsSuperTokens SDK for vanilla JS for all recipes7016

iOS

supertokens/supertokens-iosiOS SDK for SuperTokens147

React Native

supertokens/supertokens-react-nativeReact Native SDK for SuperTokens3016

Android

supertokens/supertokens-androidAndroid SDK for SuperTokens81

SDK configuration

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

let appInfo: {
  appName: string;
  websiteDomain: string;
  apiDomain: string;
  websiteBasePath?: 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/*. This configuration can change by using the websiteBasePath configuration.

On the frontend, the domain serves 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/*. This configuration can change 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 "/".

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 does not see that sub path (the gateway removes /dev/ and /prod/).

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 SuperTokens.
  • If you set this and not apiBasePath, then the frontend SDK queries {apiDomain}{apiGatewayPath}/auth/* to reach the endpoints exposed by SuperTokens.

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 as the gateway removes them. Taking the above example, whilst the frontend queries {apiDomain}/development/supertokens/*, the backend SDK sees {apiDomain}/supertokens/*.


API reference

API schema and response details