supertokens · promptless · Mar 29, 2025
diff --git a/v3/docs/references/backend-sdks/reference.mdx b/v3/docs/references/backend-sdks/reference.mdx
@@ -0,0 +1,182 @@
+---
+title: Reference
+hide_title: true
+sidebar_position: 1
+description: >-
+  Override frontend authentication functions using SuperTokens for custom
+  session and user sign-up logic.
+---
+
+import {
+  FrontendPrebuiltUITabs,
+} from "/src/components/Tabs";
+
+# Backend SDKs
+
+## 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.
+
+## Customization
+
+<ReferenceCard.Grid>
+  <ReferenceCard href="https://supertokens.com/docs/auth-react">
+    <ReferenceCard.Title>
+      Function overrides
+    </ReferenceCard.Title>
+  </ReferenceCard>
+  <ReferenceCard href="https://supertokens.com/docs/auth-react">
+    <ReferenceCard.Title>
+      API overrides
+    </ReferenceCard.Title>
+  </ReferenceCard>
+
+  <ReferenceCard href="https://supertokens.com/docs/auth-react">
+    <ReferenceCard.Title>
+      Hooks
+    </ReferenceCard.Title>
+  </ReferenceCard>
+
+
+</ReferenceCard.Grid>
+
+
+
+## SDK references
+
+<ReferenceCard.Grid>
+  <ReferenceCard href="https://supertokens.com/docs/nodejs">
+    <ReferenceCard.Avatar icon="node" />
+    <ReferenceCard.Title>
+      NodeJS
+    </ReferenceCard.Title>
+  </ReferenceCard>
+
+  <ReferenceCard href="https://supertokens.com/docs/golang">
+    <ReferenceCard.Avatar icon="go" />
+    <ReferenceCard.Title>
+      GoLang
+    </ReferenceCard.Title>
+  </ReferenceCard>
+
+  <ReferenceCard href="https://supertokens.com/docs/python">
+    <ReferenceCard.Avatar icon="python" />
+    <ReferenceCard.Title>
+      Python
+    </ReferenceCard.Title>
+  </ReferenceCard>
+</ReferenceCard.Grid>
+
+
+## SDK configuration
+
+The `appInfo` object is the paramter used to configure the SDKs during initialization.
+```ts
+let appInfo: {
+    applicationName: string,
+    websiteDomain: string,
+    apiDomain: string,
+    websiteBasePath?: string,  
+    apiBasePath?: string,  
+    apiGatewayPath?: string 
+}
+```
+
+<Accordion px="4" pb="4">
+
+## `applicationName` 
+
+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 `applicationName: "GitHub"`.
+
+<br/>
+
+## `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.
+
+<br/>
+
+## `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.
+
+<br/>
+
+## `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 `"/"`.
+
+:::important
+Remember to set the same value for this parameter on the backend and the frontend.
+:::
+
+<br/>
+
+
+## `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}/*`
+
+:::important
+Remember to set the same value for this parameter on the backend and the frontend.
+:::
+
+:::caution
+Note that setting a custom `apiBasePath` updates the refresh API path, this can cause an issue where previously issued refresh tokens no longer get sent to the new API endpoint and the user logs out.
+For example, the default `apiBasePath` value is `/auth`, if it changes to `/supertokens`, then your refresh endpoint updates from `/auth/session/refresh` to `/supertokens/session/refresh`.
+Previously issued refresh tokens do not get sent to the new API endpoint and the user logs out.
+:::
+
+
+<br/>
+
+## `apiGatewayPath` 
+
+:::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 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/*`.
+
+<br/>
+
+</Accordion>
+