---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk/interfaces/AuthApi.md
---
[Reference](../../../index.md) / [@getenginex/sdk](../index.md) / 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`](CallOptions.md)

#### 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`](CallOptions.md)

#### 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`](CallOptions.md)

#### Returns

`Promise`<`void`>

#### Example

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

#### Throws

`UNAUTHENTICATED`, `2FA_INVALID`, `INVALID_CREDENTIALS`.

***

### enable2fa()

> **enable2fa**(`params?`, `options?`): `Promise`<[`TwoFactorSetup`](TwoFactorSetup.md)>

Starts enabling 2FA; show the QR code and confirm with [AuthApi.verify2fa](#verify2fa).

#### Parameters

##### params?

[`NoParams`](../type-aliases/NoParams.md)

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`TwoFactorSetup`](TwoFactorSetup.md)>

#### 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`](CallOptions.md)

#### Returns

`Promise`<`void`>

#### Example

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

***

### login()

> **login**(`input`, `options?`): `Promise`<[`LoginResult`](../type-aliases/LoginResult.md)>

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`](../type-aliases/LoginInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`LoginResult`](../type-aliases/LoginResult.md)>

#### 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`](../type-aliases/NoParams.md)

##### options?

[`CallOptions`](CallOptions.md)

#### 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`](CpfLookupResult.md)>

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`](CallOptions.md)

#### Returns

`Promise`<[`CpfLookupResult`](CpfLookupResult.md)>

#### 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`](RegisterResult.md)>

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

#### Parameters

##### input

[`RegisterInput`](RegisterInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`RegisterResult`](RegisterResult.md)>

#### 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`](CallOptions.md)

#### 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`](CallOptions.md)

#### 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`](CallOptions.md)

#### 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`](CallOptions.md)

#### 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`](SaveLeadInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### 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`](CallOptions.md)

#### 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`](../type-aliases/VerifyEmailInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### 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`](CallOptions.md)

#### Returns

`Promise`<`void`>

#### Example

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

#### Throws

`INVALID_ARGUMENT` for a wrong or expired OTP.
