Skip to main content

About appInfo

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

type 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. 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".
  • If you have multiple sub domains with their own login pages (ex 'https://staff.example.com/login' and 'https://user.example.com/login'), then the value of this should be the main domain "https://example.com" on the backend, and on each frontend, it should be the respective subdomain "https://staff.example.com" and "https://user.example.com".

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/*.

websiteBasePath (optional)#

There is no need to define this for the session only recipe. This is used to display the login ui and handle the login system in other recipes.

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.

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/*.

Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react