RegisterLogin
DocsPricing
RegisterLogin
  • Getting Started
  • Introduction
  • Quick Start
  • SDKs
  • React
  • TypeScript
  • Next.js
  • Express
  • NestJS
  • Python
  • API Reference
  • Support and Resources
  • FAQ
  • Contact Support

AuthSafe

Product

HighlightFeatureIntegrationPricingFAQ

Company

AboutBlogContactSitemap

Developer

DashboardDocumentation

Legal

Terms & ConditionsPrivacyComplianceShippingCancellation

© 2026 AuthSafe. All rights reserved.

We value your privacy

This website uses cookies for anonymous analytics to help us improve your experience. No personal information is stored or shared. You can allow or reject analytics tracking at any time. See our Privacy Policy.

We use cookies for anonymous analytics. No personal info is stored. See our Privacy Policy.

OAuthService

Main service for OAuth 2.1 and OpenID Connect authentication flows.

Overview

The OAuthService manages the complete OAuth 2.1 and OIDC authentication lifecycle with automatic PKCE, state validation, nonce handling, and token refresh.
Built on oidc-client-ts
OAuthService wraps the industry-standard oidc-client-ts library with AuthSafe-specific configuration and additional features like cross-tab synchronization and automatic refresh token management.

Constructor

import { OAuthService } from 'authsafe-ts';

const oauthService = new OAuthService(config: OAuthConfig);

Configuration

PropertyTypeRequiredDescription
clientIdstringYesOAuth client ID from AuthSafe dashboard
redirectUristringYesCallback URL after authentication
scopestring[]NoRequested scopes. Default: ['openid', 'email', 'profile']
authoritystringNoCustom authority URL (auto-detected if not provided)
popupRedirectUristringNoCallback URL for popup authentication
silentRedirectUristringNoCallback URL for silent token refresh
automaticSilentRenewbooleanNoEnable automatic token renewal. Default: false
env'development' | 'production'NoEnvironment for cookie security

Methods

Authentication

// Redirect-based login
await oauthService.signinRedirect(extraQueryParams?: Record<string, string>): Promise<void>

// Popup-based login
await oauthService.signinPopup(extraQueryParams?: Record<string, string>): Promise<User>

// Process redirect callback
await oauthService.signinRedirectCallback(): Promise<User>

// Process popup callback
await oauthService.signinPopupCallback(): Promise<void>

// Silent token refresh
await oauthService.signinSilent(): Promise<User | null>

// Process silent callback
await oauthService.signinSilentCallback(url?: string): Promise<void>

Logout

// Redirect-based logout
await oauthService.signoutRedirect(options?: SignoutOptions): Promise<void>

// Popup-based logout
await oauthService.signoutPopup(options?: SignoutOptions): Promise<void>

// Local logout only
await oauthService.removeUser(): Promise<void>

User & Tokens

// Get current user
await oauthService.getUser(): Promise<User | null>

// Initialize and restore session
await oauthService.initialize(): Promise<void>

// Refresh tokens manually
await oauthService.refreshToken(refreshToken: string): Promise<TokenResponse>

// Refresh and store tokens
await oauthService.refreshAndStoreTokens(refreshToken: string): Promise<TokenResponse>

// Fetch user profile
await oauthService.fetchUserInfo(accessToken: string): Promise<any>

// Revoke token
await oauthService.revokeToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<void>

Event Listeners

// State change (any auth event)
oauthService.onStateChange(callback: () => void): void

// User loaded
oauthService.onUserLoaded(callback: (user: User) => void): void

// User unloaded
oauthService.onUserUnloaded(callback: () => void): void

// Token expiring
oauthService.onAccessTokenExpiring(callback: () => void): void

// Token expired
oauthService.onAccessTokenExpired(callback: () => void): void

// Silent renew error
oauthService.onSilentRenewError(callback: (error: Error) => void): void

// Session changed
oauthService.onUserSessionChanged(callback: () => void): void

Example Usage

import { OAuthService } from 'authsafe-ts';

const oauthService = new OAuthService({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scope: ['openid', 'profile', 'email', 'offline_access'],
  automaticSilentRenew: true,
  silentRedirectUri: 'https://yourapp.com/silent-callback',
  env: 'production',
});

// Setup event listeners
oauthService.onUserLoaded((user) => {
  console.log('User authenticated:', user.profile);
});

// Initialize on app startup
await oauthService.initialize();

// Login
await oauthService.signinRedirect();

// On callback page
const user = await oauthService.signinRedirectCallback();

// Logout
await oauthService.signoutRedirect();

Best Practices

  1. Always call initialize() on app startup to restore sessions
  2. Include offline_access scope for refresh tokens
  3. Enable automatic silent renewal for seamless UX
  4. Use environment variables for configuration
  5. Handle token expiration gracefully with event listeners

Related

  • HttpService - HTTP client for API requests
  • Type Definitions - TypeScript types
  • TypeScript SDK Overview