This document provides a high-level introduction to the auth0.js SDK version 9.30.1, a client-side JavaScript library for implementing authentication and authorization in browser-based applications. It covers the SDK's purpose, architecture, three main client classes (WebAuth, Authentication, Management), distribution formats, and high-level capabilities.
For detailed installation instructions and configuration examples, see Installation & Setup. For in-depth architectural details and component relationships, see Core Architecture & Client Types. For migration information from earlier versions, see Version 9 Migration Guide.
Auth0.js is a headless browser SDK that provides JavaScript clients for integrating Auth0 authentication and authorization services into web applications. Unlike hosted solutions, this SDK enables embedded authentication flows directly within your application's UI while maintaining secure communication with Auth0's cloud platform.
The SDK implements OpenID Connect (OIDC) and OAuth 2.0 protocols, handling token management, session validation, and secure authentication flows without requiring a full page redirect in certain scenarios.
Key Characteristics:
Sources: package.json1-22 README.md1-17
The current version (9.30.1) represents the v9 lineage, which introduced significant architectural changes from v8:
| Feature | Description |
|---|---|
| Cross-Origin Authentication | Uses /co/authenticate endpoint for embedded login scenarios |
| Web Message Handler | Implements postMessage communication for silent authentication |
| Enhanced Security | Mandatory ID token verification (RS256/HS256), access token hash validation |
| Cookie-First Storage | Defaults to cookies with localStorage fallback for third-party cookie restrictions |
| Transaction Management | 30-minute expiration for state/nonce parameters with secure cleanup |
| Organization Support | Validates organization claims (org_id, org_name) in ID tokens |
| CAPTCHA Integration | Supports Auth0, Arkose, hCaptcha, Friendly Captcha, and reCAPTCHA Enterprise |
Breaking Change (v8 → v9): Version 9 removed API calls to deprecated endpoints (usernamepassword/login, user/ssodata) and mandates cross-origin authentication setup. Applications using Hosted Login Pages in certain configurations should carefully review compatibility.
Sources: CHANGELOG.md1-827 src/version.js1
Auth0.js exposes three distinct client classes, each serving different use cases. Applications can instantiate only the clients they need.
Diagram: Three Client Classes and Their Purposes
The WebAuth class is the primary entry point for most applications. It orchestrates complete authentication flows including redirects, popups, silent authentication, and passwordless flows.
Key Responsibilities:
authorize() or login()parseHash()checkSession() and renewAuth()popup sub-componentredirect sub-componentThe Authentication class provides low-level access to Auth0 Authentication API endpoints without the orchestration layer. Use this when you need direct API control or are implementing custom flows.
Key Responsibilities:
The Management class provides client-side access to specific Auth0 Management API endpoints related to user profile management. Requires an access token with appropriate https://YOUR_DOMAIN.auth0.com/api/v2/ audience.
Key Responsibilities:
Sources: README.md42-75 package.json1-23
The SDK follows a layered architecture where high-level clients compose mid-level services and low-level utilities.
Diagram: Component Composition and Dependencies
| Layer | Components | Purpose |
|---|---|---|
| Public API | WebAuth, Authentication, Management | Developer-facing interfaces, parameter validation |
| Flow Components | Popup, Redirect, HostedPages | Strategy implementations for different authentication flows |
| Core Services | CrossOriginAuthentication, TransactionManager, message handlers | Security, state management, cross-domain communication |
| Utilities | IdTokenVerifier, RequestBuilder, Storage, helpers | Low-level operations, HTTP, validation, storage abstraction |
Sources: README.md77-115
Auth0.js is distributed in two primary formats to support different integration patterns:
Diagram: Distribution Formats and Integration Patterns
| Format | Entry Point | Target | Use Case |
|---|---|---|---|
| ES2015 Module | dist/auth0.min.esm.js | Modern bundlers (Webpack, Rollup, Vite) | Tree-shaking, modern JavaScript features |
| ES5 CommonJS | dist/auth0.min.js | Legacy bundlers, direct browser inclusion | Maximum compatibility, IE11 support |
CDN files include Subresource Integrity (SRI) hashes for integrity verification. The CDN uploader configuration generates SHA-384 hashes automatically during the build process.
Sources: package.json7-14 package.json116-130 README.md23-40
The following table summarizes the major capabilities provided by auth0.js and which client class exposes them:
| Capability | WebAuth | Authentication | Management | Notes |
|---|---|---|---|---|
| Authorization Code Flow | ✓ | authorize() method | ||
| Implicit Flow | ✓ | authorize() with response_type | ||
| Resource Owner Password | ✓ | ✓ | login() or loginWithResourceOwner() | |
| Passwordless (Email/SMS) | ✓ | passwordlessStart() → passwordlessVerify() | ||
| Silent Authentication | ✓ | checkSession(), renewAuth() | ||
| Popup-based Flows | ✓ | popup.authorize(), popup.loginWithCredentials() | ||
| Cross-Origin Login | ✓ | /co/authenticate via Redirect | ||
| Token Parsing | ✓ | parseHash() | ||
| Token Verification | ✓ | RS256 signature + claims validation | ||
| User Signup | ✓ | signup(), signupAndAuthorize() | ||
| SSO Data Retrieval | ✓ | ✓ | getSSOData() | |
| User Profile Fetch | ✓ | ✓ | /userinfo or /api/v2/users/{id} | |
| Metadata Updates | ✓ | patchUserMetadata() | ||
| Identity Linking | ✓ | linkUser() | ||
| CAPTCHA Rendering | ✓ | renderCaptcha() for Bot Detection | ||
| Logout | ✓ | logout() or buildLogoutUrl() |
Sources: README.md77-115
Sources: README.md42-75
Auth0.js has minimal runtime dependencies to keep the bundle size small:
| Dependency | Version | Purpose |
|---|---|---|
idtoken-verifier | ^2.2.4 | JWT signature verification, RS256 validation |
base64-js | ^1.5.1 | Base64 encoding/decoding utilities |
js-cookie | ^2.2.0 | Cookie storage abstraction |
qs | ^6.10.1 | Query string parsing and stringification |
superagent | ^10.2.3 | HTTP client for API requests |
url-join | ^4.0.1 | URL path joining utility |
winchan | ^0.2.2 | Cross-window communication for popup flows |
These dependencies are bundled into the distributed files, so no additional installation is required when using the CDN.
Sources: package.json55-63
Auth0.js implements multiple security layers (detailed documentation in Security Considerations):
at_hash claim when present in ID tokensorg_id or org_name claims when organization context is providedSources: CHANGELOG.md825-831
Refresh this wiki