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?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
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?
options?
Returns
Promise<TwoFactorSetup>
Example
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?
Returns
Promise<void>
Example
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
options?
Returns
Promise<LoginResult>
Example
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?
options?
Returns
Promise<void>
Example
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?
Returns
Promise<CpfLookupResult>
Example
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
options?
Returns
Promise<RegisterResult>
Example
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?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
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
options?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
await enginex.auth.verify2fa({ twoFactorCode: '123456' })Throws
UNAUTHENTICATED, 2FA_INVALID.
verifyEmail()
verifyEmail(
input,options?):Promise<void>
Confirms the email.
Parameters
input
options?
Returns
Promise<void>
Example
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?
Returns
Promise<void>
Example
await enginex.auth.verifyPhone({ userId, otp: '1234' })Throws
INVALID_ARGUMENT for a wrong or expired OTP.