Class ESPRMAuth

The ESPRMAuth class provides comprehensive authentication functionality for users. It includes methods for account sign-up, login, password management, OTP-based authentication, and OAuth-based login flows. Key features include:

  • Sign-Up Process: Methods to send sign-up codes and confirm user registration.
  • Password Management: Support for password recovery, setting new passwords, and login with credentials.
  • OTP-Based Login: Methods to request and validate OTPs for secure access.
  • OAuth Authentication: Support for initiating and completing login using OAuth codes.
  • Federated Sign-In: Support for exchanging a provider issued ID token, obtained natively, for RainMaker session tokens.
  • Session Management: Provides functionality to fetch details of the currently logged-in user.

This class simplifies the integration of authentication mechanisms in applications built on the ESP RainMaker ecosystem.

Constructors

constructor

Methods

confirmSignUp forgotPassword getLoggedInUser login loginWithFederatedToken loginWithOauth loginWithOauthCode loginWithOTP requestLoginOTP sendSignUpCode setNewPassword

Constructors

constructor

Methods

confirmSignUp

  • confirmSignUp(
        username: string,
        verificationCode: string,
        tags?: string[],
    ): Promise<ESPAPIResponse>

    Confirms a user’s account by verifying the username and confirmation code. Optionally, tags can be provided.

    Parameters

    • username: string

      The username of the user to confirm.

    • verificationCode: string

      The code sent to the user for verification.

    • Optionaltags: string[]

      Optional tags associated with the user.

    Returns Promise<ESPAPIResponse>

    A promise that resolves with an ESPAPIResponse object if the user is successfully signed up.

forgotPassword

  • forgotPassword(username: string): Promise<ESPAPIResponse>

    Initiates the forgot password flow for a user by sending their username to the API.

    Parameters

    • username: string

      The username of the user who wants to reset their password.

    Returns Promise<ESPAPIResponse>

    A promise that resolves with an ESPAPIResponse indicating success.

getLoggedInUser

  • getLoggedInUser(): Promise<null | ESPRMUser>

    Retrieves the currently logged-in user.

    This method checks if the access token is available and valid. If the access token is expired, it attempts to refresh the session using the refresh token. If successful, it returns an instance of the ESPRMUser class containing the user's tokens. If no valid access token is found, it returns null.

    Returns Promise<null | ESPRMUser>

    A promise that resolves to an instance of ESPRMUser if the user is logged in, or null if not.

login

  • login(username: string, password: string): Promise<ESPRMUser>

    Logs in a user by their username and password, returning an ESPRMUser instance upon success.

    Parameters

    • username: string

      The username of the user logging in.

    • password: string

      The password of the user.

    Returns Promise<ESPRMUser>

    A promise that resolves to an instance of ESPRMUser containing the user's tokens.

    Throws

    ESPValidationError if the password is missing.

loginWithFederatedToken

  • loginWithFederatedToken(provider: string, idToken: string): Promise<ESPRMUser>

    Logs in a user by exchanging a provider issued ID token for RainMaker session tokens.

    Unlike ESPRMAuth.loginWithOauth, this method needs no browser redirect and no OAuth adapter. The caller obtains the ID token on-device using the provider's native SDK — for example the Google Sign-In SDK or Sign in with Apple — and this method exchanges it for RainMaker tokens, returning an authenticated ESPRMUser.

    Parameters

    • provider: string

      The federated identity provider that issued the ID token. ESPFederatedProvider.GOOGLE and ESPFederatedProvider.APPLE are supported; providers reserved for future use, such as facebook and wechat, are rejected with error code 101113.

    • idToken: string

      The ID token issued by the provider.

    Returns Promise<ESPRMUser>

    A promise that resolves to an instance of ESPRMUser containing the access, ID, and refresh tokens.

    Throws

    ESPAPICallValidationError if the provider or the ID token is missing.

    Remarks

    This route is not deployed in the China region, where the request fails at the API gateway, and it is rejected with error code 100052 on oauth-only deployments.

    Example

    const user = await authInstance.loginWithFederatedToken(
      ESPFederatedProvider.GOOGLE,
      googleIdToken
    );

loginWithOauth

  • loginWithOauth(identityProvider: string): Promise<ESPRMUser>

    Logs a user in with an identity provider, using the best flow available.

    When a nativeLoginAdapter is configured and offers an on-device flow for this provider, the provider's own account UI is shown and the ID token it returns is exchanged through ESPRMAuth.loginWithFederatedToken. Otherwise the browser based OAuth flow runs: an authorization code is requested through the oauthAdapter and exchanged via ESPRMAuth.loginWithOauthCode.

    Callers do not choose between the two — that decision, the exchange, and token persistence all belong to the SDK.

    Parameters

    • identityProvider: string

      The identity provider to log in with.

    Returns Promise<ESPRMUser>

    A promise that resolves to an instance of ESPRMUser containing user tokens.

loginWithOauthCode

  • loginWithOauthCode(
        code: string,
        options?: LoginWithOauthCodeOptions,
    ): Promise<ESPRMUser>

    Exchanges a previously obtained OAuth authorization code for user tokens.

    Unlike ESPRMAuth.loginWithOauth, this method does not request the code itself. The caller supplies an authorization code that was already acquired out-of-band — for example, from the WeChat native SDK in the CN region — and this method performs only the token-exchange step, returning an authenticated ESPRMUser.

    Parameters

    • code: string

      The OAuth authorization code to exchange for tokens.

    • Optionaloptions: LoginWithOauthCodeOptions

      Optional flags controlling the exchange. Set wechatTokenOnly to add the wechat_token_only=true flag required by the WeChat token exchange; it also sends the WeChat identity_provider by default, which identityProvider overrides.

    Returns Promise<ESPRMUser>

    A promise that resolves to an instance of ESPRMUser containing the access, ID, and refresh tokens.

    Throws

    ESPAPICallValidationError if the code or the required SDK config (auth URL, client ID) is missing.

loginWithOTP

  • loginWithOTP(
        username: string,
        verificationCode: string,
        sessionToken: string,
    ): Promise<ESPRMUser>

    Logs in a user using an OTP (One-Time Password) and a session token.

    Parameters

    • username: string

      The username of the user attempting to log in.

    • verificationCode: string

      The OTP received by the user.

    • sessionToken: string

      The session token associated with the OTP request.

    Returns Promise<ESPRMUser>

    A promise that resolves to an instance of ESPRMUser containing user tokens.

    Throws

    ESPValidationError if the verification code or session token is missing.

requestLoginOTP

  • requestLoginOTP(username: string): Promise<string>

    Requests a login OTP (One-Time Password) for the specified username.

    Parameters

    • username: string

      The username for which the OTP is requested.

    Returns Promise<string>

    A promise that resolves to a sessionToken string indicating the OTP session.

sendSignUpCode

  • sendSignUpCode(username: string, password: string): Promise<ESPAPIResponse>

    Registers a new user by providing their username and password.

    Parameters

    • username: string

      The username for the new account.

    • password: string

      The password for the new account.

    Returns Promise<ESPAPIResponse>

    A promise that resolves to an ESPAPIResponse indicating the success in sending sign up code.

setNewPassword

  • setNewPassword(
        username: string,
        newPassword: string,
        verificationCode: string,
    ): Promise<ESPAPIResponse>

    Sets a new password for a user by providing their username, a new password, and a verification code.

    Parameters

    • username: string

      The username of the user who is setting a new password.

    • newPassword: string

      The new password to be set for the user.

    • verificationCode: string

      The verification code used to authorize the password change.

    Returns Promise<ESPAPIResponse>

    A promise that resolves to an ESPAPIResponse indicating the success of the operation.

Settings

Member Visibility

On This Page

Constructors
Methods