This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk / AuthApi

AuthApi ​

Sign-up, login, verification and password recovery, and the logged-in player's account: logout, password and phone change, and 2FA enabling/disabling.

Methods ​

changePassword() ​

changePassword(input, options?): Promise<void>

Changes the logged-in player's password.

Parameters ​

input ​
currentPassword ​

string

newPassword ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.changePassword({ currentPassword, newPassword })

Throws ​

UNAUTHENTICATED, INVALID_CREDENTIALS, PASSWORD_SAME_AS_CURRENT.


confirmPhoneChange() ​

confirmPhoneChange(input, options?): Promise<void>

Confirms the phone change with the OTP.

Parameters ​

input ​
otp ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.confirmPhoneChange({ otp: '4321' })

Throws ​

UNAUTHENTICATED, INVALID_ARGUMENT.


disable2fa() ​

disable2fa(input, options?): Promise<void>

Disables 2FA.

Parameters ​

input ​
password ​

string

twoFactorCode ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.disable2fa({ twoFactorCode: '123456', password })

Throws ​

UNAUTHENTICATED, 2FA_INVALID, INVALID_CREDENTIALS.


enable2fa() ​

enable2fa(params?, options?): Promise<TwoFactorSetup>

Starts enabling 2FA; show the QR code and confirm with AuthApi.verify2fa.

Parameters ​

params? ​

NoParams

options? ​

CallOptions

Returns ​

Promise<TwoFactorSetup>

Example ​

ts
const { qrCode, backupCodes } = await enginex.auth.enable2fa()

Throws ​

UNAUTHENTICATED.


forgotPassword() ​

forgotPassword(input, options?): Promise<void>

Sends the recovery email. It always resolves, so as not to reveal whether the email exists.

Parameters ​

input ​
email ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.forgotPassword({ email: 'ana@exemplo.com' })

login() ​

login(input, options?): Promise<LoginResult>

Logs in with email or CPF. If the account has 2FA, it returns 2fa_required: ask for the code and call again with twoFactorCode.

Parameters ​

input ​

LoginInput

options? ​

CallOptions

Returns ​

Promise<LoginResult>

Example ​

ts
let result = await enginex.auth.login({ email, password })
if (result.status === '2fa_required') {
  result = await enginex.auth.login({ email, password, twoFactorCode: await askCode() })
}

Throws ​

INVALID_CREDENTIALS, ACCOUNT_LOCKED, ACCOUNT_SUSPENDED, SELF_EXCLUDED, 2FA_INVALID; VALIDATION_ERROR when the response does not carry the tokens (nothing is stored); CONFIGURATION_ERROR with sessionOwner: 'app', without a request (the app does its own login).


logout() ​

logout(params?, options?): Promise<void>

Ends the session. It never throws: the local session is cleared even if revoking on the server fails. Sends the stored refresh token, so the gateway revokes it too (it cannot be used to renew afterwards). With an expired access token the gateway refuses the call before revoking: logout then renews the session once (without storing the new tokens nor calling onSessionExpired) and revokes the renewed refresh token. If that renewal or the second call fails, the refresh token may stay valid on the server until it expires. Exceptions, both with EnginexError CONFIGURATION_ERROR, without a request and without touching the tokenStore: after client.dispose() (like any other method of a disposed client) and with sessionOwner: 'app' (the app ends the session through its own authentication).

Parameters ​

params? ​

NoParams

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.logout()

Throws ​

CONFIGURATION_ERROR with a disposed client or with sessionOwner: 'app'.


lookupCpf() ​

lookupCpf(input, options?): Promise<CpfLookupResult>

Looks up the CPF at the Receita Federal to pre-fill name and date of birth. Accepts a masked CPF.

Parameters ​

input ​
captchaToken? ​

string

cpf ​

string

options? ​

CallOptions

Returns ​

Promise<CpfLookupResult>

Example ​

ts
try {
  const { name, birthDate } = await enginex.auth.lookupCpf({ cpf: '123.456.789-09' })
} catch (e) {
  if (isEnginexError(e, 'captcha_required')) showCaptcha(e.details?.site_key)
}

Throws ​

captcha_required (428), cpf_already_registered (409), cpf_validation_failed (422), rate_limited (429).


register() ​

register(input, options?): Promise<RegisterResult>

Creates the account. It does not log in: next, verify the email/phone and call AuthApi.login.

Parameters ​

input ​

RegisterInput

options? ​

CallOptions

Returns ​

Promise<RegisterResult>

Example ​

ts
const { userId } = await enginex.auth.register({
  email: 'ana@exemplo.com', password: 'Senha@123', cpf: '12345678909',
  name: 'Ana Souza', birthDate: '1990-01-01', captchaToken,
})

Throws ​

EMAIL_ALREADY_EXISTS, CPF_ALREADY_EXISTS, INVALID_ARGUMENT.


requestPhoneChange() ​

requestPhoneChange(input, options?): Promise<void>

Requests a phone change; the gateway sends an OTP to the new number.

Parameters ​

input ​
newPhone ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.requestPhoneChange({ newPhone: '11988887777' })

Throws ​

UNAUTHENTICATED, INVALID_PHONE.


resendPhoneVerification() ​

resendPhoneVerification(input, options?): Promise<void>

Resends the phone OTP.

Parameters ​

input ​
userId ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.resendPhoneVerification({ userId })

Throws ​

RESOURCE_EXHAUSTED when the resend limit is reached.


resendVerificationEmail() ​

resendVerificationEmail(input, options?): Promise<void>

Resends the email verification code.

Parameters ​

input ​
userId ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.resendVerificationEmail({ userId })

resetPassword() ​

resetPassword(input, options?): Promise<void>

Sets the new password with the token received by email.

Parameters ​

input ​
email ​

string

newPassword ​

string

token ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.resetPassword({ email, token, newPassword: 'Nova@123' })

Throws ​

TOKEN_INVALID, TOKEN_EXPIRED, INVALID_ARGUMENT.


saveLead() ​

saveLead(input, options?): Promise<void>

Records the sign-up progress for marketing. It never blocks the flow.

Parameters ​

input ​

SaveLeadInput

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.saveLead({ cpf, stepCompleted: 'cpf', utmSource: 'google' })

verify2fa() ​

verify2fa(input, options?): Promise<void>

Confirms enabling 2FA with the first code from the app.

Parameters ​

input ​
twoFactorCode ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.verify2fa({ twoFactorCode: '123456' })

Throws ​

UNAUTHENTICATED, 2FA_INVALID.


verifyEmail() ​

verifyEmail(input, options?): Promise<void>

Confirms the email.

Parameters ​

input ​

VerifyEmailInput

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.verifyEmail({ userId, code: '123456' })

Throws ​

TOKEN_INVALID, TOKEN_EXPIRED.


verifyPhone() ​

verifyPhone(input, options?): Promise<void>

Confirms the phone with the OTP sent by SMS.

Parameters ​

input ​
otp ​

string

userId ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.auth.verifyPhone({ userId, otp: '1234' })

Throws ​

INVALID_ARGUMENT for a wrong or expired OTP.