Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

About appInfo

The appInfo object is to be specified on the frontend as well as on the backend.

let appInfo: {
    appName: string,
    websiteDomain: string,
    apiDomain: string,
    websiteBasePath?: string,  // optional
    apiBasePath?: string,  // optional
    apiGatewayPath?: string // optional
}

appName (compulsory)#

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

websiteDomain (compulsory)#

This is the domain part of your website. This is where the login UI will be shown. 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 will be displayed on {websiteDomain}/auth/*. This can be changed by using the websiteBasePath config.

On the frontend, we need the domain for routing purposes, and on the backend, we need it so that we can generate correct email verification and password reset links.

apiDomain (compulsory)#

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 is reached via /api/*, then the value of this is the same as the websiteDomain - since /api/* is equal to querying {websiteDomain}/api/*.

By default, our login widgets will query {apiDomain}/auth/*. This can be changed by using the apiBasePath config.

websiteBasePath (optional)#

By default, the login UI will be displayed on {websiteDomain}/auth. Other auth related UIs will be shown 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 "/".
important

Remember to set the same value for this param on the backend and the frontend.

apiBasePath (optional)#

By default, our frontend SDK will query {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 our APIs not via /auth but via some other string like /supertokens, then you can set the value of this to "/supertokens". This means, our APIs will be exposed on {apiDomain}/supertokens/*.
  • If you do not want to scope our APIs at all, then you can set the values of this to be "/". This means our APIs will be available on {apiDomain}/*
important

Remember to set the same value for this param on the backend and the frontend.

caution

Note that setting a custom apiBasePath will update the refresh API path, this can cause an issue where previously issued refresh tokens will no longer get sent to the new API endpoint and the user will be logged out. For example, the default apiBasePath value is /auth, if it is changed to /supertokens, then your refresh endpoint will be updated from /auth/session/refresh to /supertokens/session/refresh. Previously issued refresh tokens will not be sent to the new API endpoint and the user will be logged out.

apiGatewayPath (optional)#

note

Most relevant if you are using an API gateway or reverse proxy

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 would be exposed via {apiDomain}/dev/*, and for production, they may be exposed via {apiDomain}/prod/*.

Whilst the frontend would need to use the /dev/ and /prod/, your backend code would not see that sub path (i.e. /dev/ and /prod/ are stripped away by the gateway).

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

The reason we have this distinction between apiGatewayPath and apiBasePath is that when routing, our backend SDK will not see the apiGatewayPath path from the request as they are stripped away by the gateway. Taking the above example, whilst the frontend queries {apiDomain}/development/supertokens/*, our backend SDK will see {apiDomain}/supertokens/*.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI