docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js) - #1395
Open
tusharpandey13 wants to merge 10 commits into
Open
docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js)#1395tusharpandey13 wants to merge 10 commits into
tusharpandey13 wants to merge 10 commits into
Conversation
…-server-js Add AUTH_MIGRATION_GUIDE.md covering the surgical migration of the Authentication layer off the auth0 package (AuthenticationClient, UserInfoClient) to @auth0/auth0-auth-js (stateless token grants) and @auth0/auth0-server-js (server-managed sessions). ManagementClient is out of scope and stays on auth0. Link the new guide from the README documentation list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3 tasks
Contributor
Author
|
Related PRs:
|
This was referenced Aug 27, 2026
Source-verified every API claim against auth0-auth-js and auth0-server-js.
Fix the mismatches found:
- fullResponse: remove the fabricated "token cache is bypassed" behavior.
auth0-auth-js AuthClient has no token cache; grant methods always hit the
endpoint. Token caching lives in auth0-server-js. Only discovery/JWKS is cached.
- getTokenByCode: options are codeVerifier and organization; there is no
expectedState parameter (that is on getTokenByMagicLinkCode). Corrected the
code comment and the state-handling note.
- initiateBackchannelAuthentication: scope goes via authorizationParams.scope,
not a top-level key; loginHint is an object ({ sub }), not a bare string.
- server-js re-exports: it DOES re-export ApiResponse and FullResponseOption
(alongside RequestOptions), not just RequestOptions.
- Custom store base class is AbstractStateStore (the exported name), not
AbstractSessionStore.
- serverClient.revokeRefreshToken also accepts an explicit { token }; noted it
defaults to the session refresh token.
- mfa.* list now includes deleteAuthenticator.
- changePassword accepts email OR username (plus connection), not email alone.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tusharpandey13
force-pushed
the
docs/auth-migration-guide
branch
from
August 27, 2026 12:18
98aeddc to
a2ef5c8
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1395 +/- ##
=======================================
Coverage 89.83% 89.83%
=======================================
Files 446 446
Lines 21371 21371
Branches 9999 9999
=======================================
Hits 19198 19198
Misses 2173 2173
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Contributor
Author
|
The |
Split the Authentication Migration Guide into a priority-ordered hub plus a migration/ directory, and wire it to the migrate-node-auth0 agent skill. - Add an agent-skill callout at the top pointing to the auth0 skill (auth0/agent-skills, intent migrate-node-auth0) so agents follow the exact rewrite rules. - Add a Directory table splitting the work into P0 (OIDC token grants + cross-cutting breaking changes, in the main file), P1 (other flows), and P2 (session apps). - Add a "Migrating only OIDC, while staying on v6" section so readers can do the OIDC migration incrementally without upgrading to v7 or migrating other flows. - Move database / passwordless / CIBA / token-exchange / UserInfoClient into migration/other-flows.md and the server-js session layer into migration/sessions.md. - Link the new directory and skill from the README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Apply migration-doc patterns from surveying Firebase, AWS, Angular, Vue, React Router, MUI, and others. - Add an anchor-linked Contents table of contents at the top. - Add a "How to use this guide" section: state it is a reference, not a linear read, and map the work to Before / During / After phases (Angular update-guide pattern) alongside the P0/P1/P2 priority order. - Move the FAQ and gotchas into migration/troubleshooting.md (MUI-style dedicated troubleshooting page) and link it from the guide, README-style. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address naming and coupling confusion: a generic migration/ directory with context-dependent filenames (sessions.md, other-flows.md) that had no visible link to AUTH_MIGRATION_GUIDE.md in the file tree. - Rename migration/ -> auth-migration/ so the directory name couples to the guide and does not collide with future version migrations. - Move the main guide to auth-migration/index.md; the root AUTH_MIGRATION_GUIDE.md is now a short stub that redirects into the directory (keeps the existing README link and the v5/v6 root convention). - Rename child files to self-describing names: other-flows.md -> authentication-flows.md, sessions.md -> server-side-sessions.md. - Repoint all cross-links (guide <-> children, README, v7 reference). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The old heading "Migrating only OIDC, while staying on v6" read like the whole scope of the guide. Retitle to "Optional: migrate only OIDC while staying on v6" and add a lead clarifying it is a lower-commitment alternate path, not the guide's scope. Update the anchor and its references. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Only the OIDC section carried a P-label in its title while P1/P2 existed only in prose, which read inconsistently. Rename the heading to "OIDC token grants" and keep the P0/P1/P2 priority ordering where it is defined together, in the "How to use this guide" section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Move the optional OIDC-only path into a subsection under OIDC token grants - Drop internal implementation notes from the AI-agent skill callouts - Remove all em dashes across the guide and its pages - Replace orphaned P0 section references with named links - Cut the duplicate scope sentence from the intro (kept in Scope) - Add dedicated end-of-guide sections linking the incremental pages Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Cut bold density to budget across index, flows, and troubleshooting - Convert FAQ bold questions to headings for scannable anchors - Split over-long and over-length normative sentences - Reduce undefined-coinage counts and gloss the pre-release path - Trim a duplicated pre-release caveat and a formal verb Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
AUTH_MIGRATION_GUIDE.md, an end-user guide for migrating the Authentication API layer off theauth0package (AuthenticationClient,UserInfoClient) to the current first-party server SDKs:@auth0/auth0-auth-jsfor stateless token grants (the direct successor toAuthenticationClient)@auth0/auth0-server-jsfor server-managed sessions (redirect login, cookies, refresh, logout)The Management API (
ManagementClient) is explicitly out of scope and stays onauth0. The guide is written to sit alongside the existing v5/v6 migration guides and matches their conventions.What the guide covers
>= 1.12.1, and the accurateRequestOptions/fullResponsepost-1.12.1 caveat.AuthClientandServerClient..oauth,.database,.passwordless,.backchannel,.tokenExchange, andUserInfoClient, with before/after code and a quick lookup table.expires_in→expiresAtexpiry bug, and the typed error model withisMfaRequiredError().startInteractiveLogin→completeInteractiveLogin→getUser/getAccessToken→logout), store setup, and non-redirect session logins.Also links the new guide from the README documentation list.
🤖 Generated with Claude Code
Related PRs