Supertab.auth

Methods reference for Supertab.auth

Supertab.auth is an entry point for authenticating a user. It abstracts the authentication flow and auth state management, allowing your application to easily implement login functionality and make authenticated requests to the Customer API.

Once a user is authenticated, the necessary authorization headers are passed to each Customer API request dispatched via Supertab.api.

Supertab.auth handles the event of token expiration and refreshes the token before attempting to make an authenticated call to the Customer API. There is no need to re-authenticate a user manually.

Properties

session

The user’s session data. null if the user is not authenticated. See AuthData for the type definition.

Example

const session = await supertabClient.auth.session;

status

The authentication status of the user.

• missing - The user is not authenticated.
• expired - The user’s session has expired and needs to be refreshed before making an authenticated request to the Customer API. See start method for more details on how to refresh the session.
• valid - The user is authenticated.

Type

enum AuthStatus {
  MISSING: "missing",
  EXPIRED: "expired",
  VALID: "valid",
}

Example

const status = await supertabClient.auth.status;

Methods

start

Initializes the authentication process when necessary and returns the user’s session data.

Based on the presence of session data:

• If session already exists, returns auth data from the browser storage.
• If session has expired, refreshes the token.
• If session is missing, opens Supertab SSO in a popup window allowing users to sign up for an account or log in to an existing account.

Parameters

silently · boolean · default: "false"

When set to true, the client does not open the Supertab SSO popup and instead attempts to refresh the session in the background. Refreshing the session is only possible if there as an existing expired session in browser storage Returns null for unknown users with no prior session.

screenHint · string · default: "register"

Specifies which screen to display in the Supertab SSO popup. Valid options are register and login.

Returns

A promise which resolves with the user’s session data object.

Field	Type	Description
accessToken	string	The access token used for making authenticated requests to the Customer API.
refreshToken	string	The token used to obtain a new access token when the current one expires.
expiresAt	Date	The date and time when the access token will expire.
tokenType	string	The type of authentication token, typically “Bearer”.

Type

type AuthData = {
  accessToken: string;
  refreshToken: string;
  expiresAt: Date;
  tokenType: string;
}

Examples

Authenticate user

// Will open the Supertab SSO popup if there is
// no session data.
await supertabClient.auth.start();

Refresh token silently

// Attempt to get session data or refresh session if
// expired. It will not open the Supertab SSO popup and
// will return `null` if the user is unknown.
await supertabClient.auth.start({ silently: true });

Authenticate user with screen hint

// Send user to the login screen in Supertab SSO.
await supertabClient.auth.start({ screenHint: "login" });

reset

Resets the authentication state by clearing the browser storage.