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 (ex8080
). 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 (ex9000
). 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 thewebsiteDomain
- 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 setapiGatewayPath: "/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/*
.