Skip to main content

Authentication

ESPRMNeoAuth registers new accounts and signs users in against your ESP RainMaker Neo deployment's User API. It is the only class you use before you have an ESPRMNeoUser, and a successful sign-in is what produces one.

Get the instance from a configured SDK; never construct it:

const auth = ESPRMNeoBase.getAuthInstance();

It throws ESPConfigError with code SDK_NOT_CONFIGURED if ESPRMNeoBase.configure() has not run.

Register an account​

Sign-up is two calls: request a verification code, then confirm it.

await auth.sendSignUpCode("<email>", "<password>");
// user reads the code from their email or SMS
await auth.confirmSignUp("<email>", "<verification-code>");

sendSignUpCode(username, password, userAttributes?) returns Promise<ESPAPIResponse>. The username decides the identity type: a value starting with + is treated as an E.164 phone number, anything else as an email address. Pass userAttributes to override that inference or to add attributes your deployment expects; explicit email or phone_number keys win over the derived one.

confirmSignUp(username, verificationCode) returns Promise<ConfirmSignUpResponse>, an optional message only. Pass the same username you signed up with so the identity type matches.

Sign in​

const user = await auth.login("<email>", "<password>");

login(username, password) returns Promise<ESPRMNeoUser>. Username is the email address or phone number the account was registered with.

Constructing the user writes its access, ID and refresh tokens through your storage adaptor, so the session is persisted as a side effect of signing in. Everything else in the SDK hangs off the returned instance.

On failure it throws ESPAuthError. Wrong credentials and an unknown account both surface as an authentication failure; branch on error.code rather than the message.

import { ESPAuthError } from "@espressif/rainmaker-neo-base-sdk";

try {
  const user = await auth.login("<email>", "<password>");
} catch (error) {
  if (error instanceof ESPAuthError) {
    console.error(error.code, error.message);
  }
  throw error;
}
There is no OTP sign-in

Password sign-in is the only interactive flow this SDK exposes. Passwordless and third-party sign-in are not part of the public surface; do not carry over requestLoginOTP or loginWithOTP call sites from other Espressif SDKs.

Restore a session on launch​

const user = await auth.getLoggedInUser();
if (!user) {
  // no stored session: show the login screen
}

getLoggedInUser() returns Promise<ESPRMNeoUser | null>. It reads the stored tokens, and if the access token has expired it refreshes the session with the refresh token before returning. null means no tokens were stored, not that they were rejected; a failed refresh throws ESPAuthError instead.

Call this on every launch before deciding what to render. It only works if a storage adaptor kept the tokens; see Adaptors.

Refresh tokens without a session​

const tokens = await ESPRMNeoAuth.getRefreshedTokens("<refresh-token>");

A static method returning Promise<UserTokensData>; the new access and ID tokens plus the refresh token you passed in. It calls the refresh endpoint unauthenticated and does not persist anything, which is what distinguishes it from ESPRMNeoUser.extendSession(). Use it when you manage token storage yourself.

getRefreshedTokens throws ESPAuthError when the response is missing either token.

Method summary​

MethodReturns
sendSignUpCode(username, password, userAttributes?)ESPAPIResponse
confirmSignUp(username, verificationCode)ConfirmSignUpResponse
login(username, password)ESPRMNeoUser
getLoggedInUser()ESPRMNeoUser | null
getRefreshedTokens(refreshToken) (static)UserTokensData

Password recovery and change are on the same class but documented separately. See Passwords.