diff --git a/v3/docs/references/backend-sdks/reference.mdx b/v3/docs/references/backend-sdks/reference.mdx new file mode 100644 index 000000000..bce8b26d3 --- /dev/null +++ b/v3/docs/references/backend-sdks/reference.mdx @@ -0,0 +1,190 @@ +--- +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 + + + + + Function overrides + + + + + API overrides + + + + + + Hooks + + + + + + + + +## SDK references + + + + + + NodeJS + + + + + + + GoLang + + + + + + + Python + + + + + +## SDK configuration + +The `appInfo` object is the paramter used to configure the SDKs during initialization. +```ts +let appInfo: { + appName: string, + websiteDomain: string, // For Python SDK, this is client_domain + apiDomain: string, + websiteBasePath?: string, // For Python SDK, this is client_base_path + 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` + +:::note +For Python SDK, this parameter is called `client_domain` +::: + +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. + +
+ +## `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. + +
+ +## `websiteBasePath` + +:::note +For Python SDK, this parameter is called `client_base_path` +::: + +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. +::: + +
+ + +## `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. +::: + + +
+ +## `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/*`. + +
+ +
+