[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / AuthService

# Class: AuthService

Platform-agnostic authentication service
Handles login, token refresh, and storage operations

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/authservice#constructor)


### Methods

- [loginTenantAdmin](/sdk-reference/classes/authservice#logintenantadmin)
- [loginUser](/sdk-reference/classes/authservice#loginuser)
- [loginBusiness](/sdk-reference/classes/authservice#loginbusiness)
- [loginUserWithRawData](/sdk-reference/classes/authservice#loginuserwithrawdata)
- [refreshAccessToken](/sdk-reference/classes/authservice#refreshaccesstoken)
- [clearTokens](/sdk-reference/classes/authservice#cleartokens)
- [isFatalAuthError](/sdk-reference/classes/authservice#isfatalautherror)
- [isDefinitiveAuthFailure](/sdk-reference/classes/authservice#isdefinitiveauthfailure)
- [handleAuthFailure](/sdk-reference/classes/authservice#handleauthfailure)
- [attemptProviderTokenRecovery](/sdk-reference/classes/authservice#attemptprovidertokenrecovery)
- [hasValidAuth](/sdk-reference/classes/authservice#hasvalidauth)
- [getCurrentUser](/sdk-reference/classes/authservice#getcurrentuser)
- [getCurrentBusiness](/sdk-reference/classes/authservice#getcurrentbusiness)
- [getCurrentAdmin](/sdk-reference/classes/authservice#getcurrentadmin)


## Constructors

### constructor

• **new AuthService**(`authApi`, `authProvider?`): [`AuthService`](/sdk-reference/classes/authservice)

#### Parameters

| Name | Type |
|  --- | --- |
| `authApi` | [`AuthApi`](/sdk-reference/classes/authapi) |
| `authProvider?` | [`TokenStorageProvider`](/sdk-reference/interfaces/tokenstorageprovider) |


#### Returns

[`AuthService`](/sdk-reference/classes/authservice)

#### Defined in

[core/auth/services/auth-service.ts:66](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L66)

## Methods

### loginTenantAdmin

▸ **loginTenantAdmin**(`jwt`, `options?`): `Promise`<`SessionAuthContextResponseDTO`>

Login tenant admin with JWT

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `jwt` | `string` | Authentication token (Firebase JWT) |
| `options?` | [`TenantAuthOptions`](/sdk-reference/interfaces/tenantauthoptions) | Tenant authentication options (tenantId for multi-tenant admins) |


#### Returns

`Promise`<`SessionAuthContextResponseDTO`>

Session response with tenant context

**`Throws`**

Error with code MULTIPLE_CONTEXT_SELECTION_REQUIRED when tenantId is required but not provided

#### Defined in

[core/auth/services/auth-service.ts:109](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L109)

### loginUser

▸ **loginUser**(`jwt`): `Promise`<`SessionAuthContextResponseDTO`>

Login user with JWT

#### Parameters

| Name | Type |
|  --- | --- |
| `jwt` | `string` |


#### Returns

`Promise`<`SessionAuthContextResponseDTO`>

#### Defined in

[core/auth/services/auth-service.ts:122](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L122)

### loginBusiness

▸ **loginBusiness**(`jwt`, `options?`): `Promise`<`SessionAuthContextResponseDTO`>

Login as business with JWT

Authenticates a user in a business context. The returned JWT contains
the user's role within that business.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `jwt` | `string` | Authentication token (passkey or Firebase JWT) |
| `options?` | [`BusinessAuthOptions`](/sdk-reference/interfaces/businessauthoptions) | Business authentication options (businessId for multi-business users) |


#### Returns

`Promise`<`SessionAuthContextResponseDTO`>

Session response with business context and role baked into JWT

**`Throws`**

MultipleContextSelectionRequiredError when businessId is required but not provided

**`Example`**

```typescript
// Auto-select if single membership
const response = await authService.loginBusiness(jwt);

// Explicit business selection
const response = await authService.loginBusiness(jwt, { businessId: 'biz-123' });
console.log('Business:', response.business?.displayName);
```

#### Defined in

[core/auth/services/auth-service.ts:153](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L153)

### loginUserWithRawData

▸ **loginUserWithRawData**(`rawLoginData`): `Promise`<`SessionAuthContextResponseDTO`>

Login user with raw data (no external auth)

#### Parameters

| Name | Type |
|  --- | --- |
| `rawLoginData` | [`RawUserData`](/sdk-reference/interfaces/rawuserdata) |


#### Returns

`Promise`<`SessionAuthContextResponseDTO`>

#### Defined in

[core/auth/services/auth-service.ts:166](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L166)

### refreshAccessToken

▸ **refreshAccessToken**(`refreshToken?`): `Promise`<`SessionAuthResponseDTO`>

Refresh access token with race condition protection

#### Parameters

| Name | Type |
|  --- | --- |
| `refreshToken?` | `string` |


#### Returns

`Promise`<`SessionAuthResponseDTO`>

#### Defined in

[core/auth/services/auth-service.ts:179](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L179)

### clearTokens

▸ **clearTokens**(): `Promise`<`void`>

Clear stored tokens and active refresh operations

#### Returns

`Promise`<`void`>

#### Defined in

[core/auth/services/auth-service.ts:225](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L225)

### isFatalAuthError

▸ **isFatalAuthError**(`errorCode`): `boolean`

Check if an error code indicates a fatal auth failure.
Fatal errors require immediate logout - the session cannot be recovered.

#### Parameters

| Name | Type |
|  --- | --- |
| `errorCode` | `undefined` | `string` |


#### Returns

`boolean`

#### Defined in

[core/auth/services/auth-service.ts:237](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L237)

### isDefinitiveAuthFailure

▸ **isDefinitiveAuthFailure**(`error`): `boolean`

Comprehensive check if an error represents a DEFINITIVE auth failure.
This is the SINGLE SOURCE OF TRUTH for determining if logout is required.

Returns true for:

- Known fatal error codes (REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc.)
- Fatal error codes in error messages (wrapped errors)


Returns false for (retryable/recoverable):

- Network errors
- Timeouts
- 5xx server errors
- TOKEN_EXPIRED (normal refresh trigger)
- Raw 401/403 without fatal code (should try refresh first)


NOTE: We intentionally DO NOT treat raw 401/403 status as fatal.
The HTTP client handles 401 by attempting token refresh first.
Only if refresh fails WITH a fatal code do we logout.

#### Parameters

| Name | Type |
|  --- | --- |
| `error` | `unknown` |


#### Returns

`boolean`

#### Defined in

[core/auth/services/auth-service.ts:260](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L260)

### handleAuthFailure

▸ **handleAuthFailure**(): `Promise`<`void`>

Handle authentication failure with provider token recovery.

Before logging out, attempts to recover the session using the stored
provider token (Firebase JWT, etc.) if it's still valid.

Recovery Flow:

1. Check if provider token exists and is not expired
2. Get the auth type (USER, BUSINESS, TENANT) to know which login to use
3. Attempt re-authentication with provider token
4. If successful: Session recovered, stay logged in
5. If failed: Clear tokens and emit AUTH_FAILED


#### Returns

`Promise`<`void`>

#### Defined in

[core/auth/services/auth-service.ts:300](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L300)

### attemptProviderTokenRecovery

▸ **attemptProviderTokenRecovery**(): `Promise`<`boolean`>

Attempt to recover session using stored provider token.
Extracts context (tenantId/businessId) from the current refresh token to ensure
the recovered session maintains the same context.

This is a PUBLIC method that can be called by TokenRefreshManager when internal
refresh fails, to try external (provider token) recovery before giving up.

#### Returns

`Promise`<`boolean`>

true if session was successfully recovered

#### Defined in

[core/auth/services/auth-service.ts:359](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L359)

### hasValidAuth

▸ **hasValidAuth**(): `Promise`<`boolean`>

Check if we have valid authentication tokens

#### Returns

`Promise`<`boolean`>

#### Defined in

[core/auth/services/auth-service.ts:433](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L433)

### getCurrentUser

▸ **getCurrentUser**(): `Promise`<`UserDTO`>

Get current authenticated user

#### Returns

`Promise`<`UserDTO`>

#### Defined in

[core/auth/services/auth-service.ts:446](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L446)

### getCurrentBusiness

▸ **getCurrentBusiness**(): `Promise`<`BusinessDTO`>

Get current business context

#### Returns

`Promise`<`BusinessDTO`>

#### Defined in

[core/auth/services/auth-service.ts:453](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L453)

### getCurrentAdmin

▸ **getCurrentAdmin**(): `Promise`<`AdminDTO`>

Get current admin context

#### Returns

`Promise`<`AdminDTO`>

#### Defined in

[core/auth/services/auth-service.ts:460](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/core/auth/services/auth-service.ts#L460)