PERS SDK - v2.3.26 / Exports / AuthService
Platform-agnostic authentication service Handles login, token refresh, and storage operations
- loginTenantAdmin
- loginUser
- loginBusiness
- loginUserWithRawData
- refreshAccessToken
- clearTokens
- isFatalAuthError
- isDefinitiveAuthFailure
- handleAuthFailure
- attemptProviderTokenRecovery
- hasValidAuth
- getCurrentUser
- getCurrentBusiness
- getCurrentAdmin
• new AuthService(authApi, authProvider?): AuthService
| Name | Type |
|---|---|
authApi | AuthApi |
authProvider? | TokenStorageProvider |
core/auth/services/auth-service.ts:66
▸ loginTenantAdmin(jwt, options?): Promise<SessionAuthContextResponseDTO>
Login tenant admin with JWT
| Name | Type | Description |
|---|---|---|
jwt | string | Authentication token (Firebase JWT) |
options? | TenantAuthOptions | Tenant authentication options (tenantId for multi-tenant admins) |
Promise<SessionAuthContextResponseDTO>
Session response with tenant context
Throws
Error with code MULTIPLE_CONTEXT_SELECTION_REQUIRED when tenantId is required but not provided
core/auth/services/auth-service.ts:109
▸ loginUser(jwt): Promise<SessionAuthContextResponseDTO>
Login user with JWT
| Name | Type |
|---|---|
jwt | string |
Promise<SessionAuthContextResponseDTO>
core/auth/services/auth-service.ts:122
▸ 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.
| Name | Type | Description |
|---|---|---|
jwt | string | Authentication token (passkey or Firebase JWT) |
options? | BusinessAuthOptions | Business authentication options (businessId for multi-business users) |
Promise<SessionAuthContextResponseDTO>
Session response with business context and role baked into JWT
Throws
MultipleContextSelectionRequiredError when businessId is required but not provided
Example
// 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);core/auth/services/auth-service.ts:153
▸ loginUserWithRawData(rawLoginData): Promise<SessionAuthContextResponseDTO>
Login user with raw data (no external auth)
| Name | Type |
|---|---|
rawLoginData | RawUserData |
Promise<SessionAuthContextResponseDTO>
core/auth/services/auth-service.ts:166
▸ refreshAccessToken(refreshToken?): Promise<SessionAuthResponseDTO>
Refresh access token with race condition protection
| Name | Type |
|---|---|
refreshToken? | string |
Promise<SessionAuthResponseDTO>
core/auth/services/auth-service.ts:179
▸ clearTokens(): Promise<void>
Clear stored tokens and active refresh operations
Promise<void>
core/auth/services/auth-service.ts:225
▸ isFatalAuthError(errorCode): boolean
Check if an error code indicates a fatal auth failure. Fatal errors require immediate logout - the session cannot be recovered.
| Name | Type |
|---|---|
errorCode | undefined | string |
boolean
core/auth/services/auth-service.ts:237
▸ 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.
| Name | Type |
|---|---|
error | unknown |
boolean
core/auth/services/auth-service.ts:260
▸ 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:
- Check if provider token exists and is not expired
- Get the auth type (USER, BUSINESS, TENANT) to know which login to use
- Attempt re-authentication with provider token
- If successful: Session recovered, stay logged in
- If failed: Clear tokens and emit AUTH_FAILED
Promise<void>
core/auth/services/auth-service.ts:300
▸ 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.
Promise<boolean>
true if session was successfully recovered
core/auth/services/auth-service.ts:359
▸ hasValidAuth(): Promise<boolean>
Check if we have valid authentication tokens
Promise<boolean>
core/auth/services/auth-service.ts:433
▸ getCurrentUser(): Promise<UserDTO>
Get current authenticated user
Promise<UserDTO>
core/auth/services/auth-service.ts:446
▸ getCurrentBusiness(): Promise<BusinessDTO>
Get current business context
Promise<BusinessDTO>
core/auth/services/auth-service.ts:453
▸ getCurrentAdmin(): Promise<AdminDTO>
Get current admin context
Promise<AdminDTO>