docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js) - #1395
Open
tusharpandey13 wants to merge 13 commits into
Open
docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js)#1395tusharpandey13 wants to merge 13 commits into
tusharpandey13 wants to merge 13 commits into
Conversation
3 tasks
Contributor
Author
|
Related PRs:
|
This was referenced Aug 27, 2026
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.67% 89.67%
========================================
Files 433 433
Lines 20911 20911
Branches 10245 9909 -336
========================================
Hits 18751 18751
Misses 2160 2160
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Contributor
Author
|
The |
…-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>
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>
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>
…flict Both migration docs PRs add the same block to the Documentation list so the insertion is identical, preventing an add/add conflict when the second PR merges. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tusharpandey13
force-pushed
the
docs/auth-migration-guide
branch
from
September 8, 2026 04:41
e77be39 to
90dc1d0
Compare
Piyush-85
previously approved these changes
Sep 8, 2026
The stateless AuthClient.getTokenByCode enforces PKCE but does NOT validate OAuth state; callers must keep their own state/CSRF check. The previous wording incorrectly told users to delete it and trust the SDK, which would silently remove CSRF protection. Also: rename callbackUrl -> url to match the real signature, replace two 'see below' prose references with anchor links.
tusharpandey13
added a commit
that referenced
this pull request
Sep 8, 2026
…uide Add ResponseError, FetchError, and JSONApiResponse to the removed-exports table; all three were removed from the v7 public entrypoint in #1397. Fix the auth0-server-js repo link (no standalone repo exists; it lives in the auth0-auth-js monorepo at packages/auth0-server-js). Remove the duplicate Authentication Migration Guide README bullet (that entry belongs to #1395 which ships the auth-migration/ directory).
…uide
The getUserInfo guidance was gated on an unmerged auth0-auth-js PR; the
feature shipped in 1.13.0, so present it as available now and drop the
raw-fetch fallback for older SDK versions.
Also: reword the AUTH_MIGRATION_GUIDE stub ("has moved" -> "lives in"),
fix the auth0-server-js links to the monorepo path (no standalone repo),
and drop the duplicate v7 guide README bullet (that entry belongs to the
v7 migration guide PR).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tusharpandey13
commented
Sep 8, 2026
tusharpandey13
left a comment
tusharpandey13
left a comment
Contributor
Author
There was a problem hiding this comment.
Review comments have been addressed
Piyush-85
approved these changes
Sep 8, 2026
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
3 participants
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