auth0 · hazel-nut · Sep 8, 2026 · Sep 8, 2026
@@ -4,7 +4,7 @@ description: Use when adding, fixing, or improving how an app authenticates user
 license: Apache-2.0
 metadata:
   author: Auth0 <support@auth0.com>
-  version: '2.1.1'
+  version: '2.2.0'
   openclaw:
     emoji: "\U0001F510"
     homepage: https://github.com/auth0/agent-skills
@@ -94,13 +94,20 @@ SDK, so check the `@capacitor/browser` rows before it.
 | `express-oauth2-jwt-bearer` | `express-jwt` |
 | `react-native-auth0` + `app.json` or `app.config.js` present | `expo` |
 | `react-native-auth0` (no Expo files) | `react-native` |
+| `@auth0/auth0-server-js` | `auth0-server-js` |
+| `@auth0/auth0-auth-js` | `auth0-auth-js` |
 | `auth0` (the bare package, not `@auth0/*`) | `node-auth0` |
 
 ### Python — check `requirements.txt` or `pyproject.toml`
 
+Rows are most-specific first: `auth0-server-python` is the framework-agnostic
+server core, so check for a co-installed web framework before falling back to the
+bare-SDK row.
+
 | Package | Framework |
 |---|---|
-| `auth0-server-python` | `flask` |
+| `auth0-server-python` + `flask` | `flask` |
+| `auth0-server-python` (no Flask web framework) | `server-python` |
 | `auth0-fastapi-api` | `fastapi-api` |
 
 ### Java / Kotlin — check `build.gradle` or `pom.xml`
@@ -150,6 +157,7 @@ SDK, so check the `@capacitor/browser` rows before it.
 | `build.gradle(.kts)` + `com.auth0.kmp:auth0` (Kotlin Multiplatform module) | `kmp` |
 | `Package.swift` or `.xcodeproj` + Auth0.swift | `swift` |
 | `build.gradle` + `com.auth0.android:auth0` | `android` |
+| `pubspec.yaml` + `auth0_flutter` + developer names/targets Windows desktop | `flutter-windows` |
 | `pubspec.yaml` + `auth0_flutter` + `flutter.web: false` | `flutter-native` |
 | `pubspec.yaml` + `auth0_flutter` + web enabled | `flutter-web` |
 
@@ -175,13 +183,14 @@ variant is resolved in "Variant disambiguation" below. As in Tier 1, check the
 | `express` in `package.json` | `express` (variant below) |
 | `fastify` in `package.json` | `fastify` (variant below) |
 | `flask` in `requirements.txt`/`pyproject.toml` | `flask` |
-| `fastapi` in `requirements.txt`/`pyproject.toml` | `fastapi-api` |
+| `fastapi` in `requirements.txt`/`pyproject.toml` | `fastapi-api` (variant below) |
 | `spring-boot` in `pom.xml`/`build.gradle` | `springboot-api` |
 | `laravel/framework` in `composer.json` | `laravel` (variant below) |
 | `composer.json` present (no Laravel) | `php` (variant below) |
 | `go.mod` present + HTTP server/router | `go` |
 | `org.jetbrains.kotlin.multiplatform` plugin + `commonMain` source set (shared Android+iOS module) | `kmp` |
 | `Package.swift` or `.xcodeproj` | `swift` |
+| `pubspec.yaml` (Flutter) + developer names/targets Windows desktop | `flutter-windows` |
 | `pubspec.yaml` (Flutter, web disabled) | `flutter-native` |
 | `pubspec.yaml` (Flutter, web enabled) | `flutter-web` |
 | `*.csproj` referencing MAUI | `maui` |
@@ -207,11 +216,14 @@ request. **Stop at the first match.**
 | React SPA (not Next.js) | `react` |
 | vanilla JS / plain JS / no framework SPA | `spa-js` |
 | node-auth0 / the `auth0` npm package | `node-auth0` |
+| `@auth0/auth0-server-js` / auth0-server-js / server-side Auth0 session SDK | `auth0-server-js` |
+| `@auth0/auth0-auth-js` / auth0-auth-js / AuthClient / low-level OAuth OIDC | `auth0-auth-js` |
 | Express (web app / server-rendered) | `express` |
 | Express API / protect API routes | `express-jwt` |
 | Fastify (web) / Fastify API | `fastify` / `fastify-api` |
 | Flask | `flask` |
-| FastAPI | `fastapi-api` |
+| FastAPI (web app) / FastAPI API | `server-python` / `fastapi-api` |
+| `auth0-server-python` / framework-agnostic Python server SDK / Python OIDC web server with no dedicated reference (Django, Starlette, Sanic, Quart, aiohttp) | `server-python` |
 | Spring Boot | `springboot-api` |
 | Java MVC / servlet | `java-mvc` |
 | ASP.NET Core web app / API | `aspnetcore-auth` / `aspnetcore-api` |
@@ -222,7 +234,7 @@ request. **Stop at the first match.**
 | Kotlin Multiplatform / KMP / shared Android+iOS auth code / `com.auth0.kmp` | `kmp` |
 | Swift / iOS | `swift` |
 | Android / Kotlin | `android` |
-| Flutter (native / web) | `flutter-native` / `flutter-web` |
+| Flutter (native / web / Windows) | `flutter-native` / `flutter-web` / `flutter-windows` |
 | React Native / Expo | `react-native` / `expo` |
 | Ionic (Angular/React/Vue) | `ionic-angular` / `ionic-react` / `ionic-vue` |
 
@@ -235,6 +247,7 @@ pin the variant, choose **intent-first**:
 |---|---|---|---|
 | express | `express` | `express-jwt` | protecting API routes / validating JWTs, no server-rendered UI |
 | fastify | `fastify` | `fastify-api` | resource server / JWT validation only |
+| fastapi | `server-python` | `fastapi-api` | resource server / JWT validation only; a web app with login/logout UI uses `server-python` |
 | php | `php` | `php-api` | building/protecting a PHP API, no web UI |
 | laravel | `laravel` | `laravel-api` | API-only (token guard), no Blade UI |
 | aspnetcore | `aspnetcore-auth` | `aspnetcore-api` | Web API / JWT bearer, no cookie login UI |
@@ -285,7 +298,6 @@ Use references/tooling-{tooling}/index.md for all Auth0 tenant configuration ste
 ```
 Read: references/feature-mfa/index.md
 Read: references/tooling-{tooling}/index.md
-If framework detected: Read references/framework-{framework}/index.md (for SDK-side step-up trigger)
 ```
 
 ### feature:organizations

@@ -56,13 +56,14 @@ Recipe (do in order):
 
 | Your context | Verify with |
 |---|---|
-| Session-managing SDK (web app) | The `amr` claim (contains `mfa` when MFA completed) off the SDK's own session / current-user accessor - already validated, so trust it as-is. Accessor name is SDK-specific -> see the `framework-*` reference. |
+| Session-managing SDK (web app) | The `amr` claim (contains `mfa` when MFA completed) off the SDK's own session / current-user accessor - already validated, so trust it as-is. Accessor name is SDK-specific -> see the SDK's own example ("Example code snippets" below). |
 | Resource API (raw bearer token) | The high-value **scope** (e.g. `transfer:funds`) on the access token, via your *existing* JWT/scope-check middleware - see "Related capabilities". |
 | Frontend | Nothing - treat any `amr` check as UX, never enforcement. |
 
 Notes: a silent token request may instead surface an `mfa_required` error - handle it by
 re-authenticating interactively. Never re-decode or re-verify the token by hand (see
-"Common mistakes"). `amr` is not a reliable contract for *which* factor ran; to enforce a
+"Common mistakes"). Some session SDKs persist only a default subset of ID-token claims, so
+`amr` can be missing from the accessor until you opt it in (see "Common mistakes"). `amr` is not a reliable contract for *which* factor ran; to enforce a
 **specific** factor, have the post-login Action read `event.authentication.methods[].type`
 into a custom claim. Action-defined MFA overrides the Guardian policy (it refines, not
 replaces) and differs from **Adaptive MFA** (the Guardian `confidence-score` policy, owned
@@ -73,7 +74,7 @@ not relax it.
 
 The app collects credentials, so no browser runs the challenge: sign-in returns an
 `mfa_required` error carrying an `mfa_token`. Each step is a method on the SDK's own MFA
-client - get exact names from the `framework-*` example; never hand-roll the token grant
+client - get exact names from the SDK's own example ("Example code snippets" below); never hand-roll the token grant
 or the MFA API URLs.
 
 Recipe (do in order):
@@ -116,7 +117,7 @@ and what the app must get right:
 
 SDK-specific symbols (an SDK's own method or option name - e.g. the silent-token call,
 the `mfa_required`/`MfaRequiredError` handling, the interactive re-auth option, refresh-token
-requirements) are **not** listed here; they belong in the relevant `framework-*` reference.
+requirements) are **not** listed here; get them from the SDK's own example (see "Example code snippets").
 
 ### `amr` claim values
 
@@ -164,7 +165,7 @@ language-neutral mechanic above. Never substitute a web search for "how to do MF
 | `@auth0/auth0-angular` (MFA) | https://raw.githubusercontent.com/auth0/auth0-angular/main/EXAMPLES.md | `## Multi-Factor Authentication (MFA)` |
 | `@auth0/auth0-angular` (step-up) | https://raw.githubusercontent.com/auth0/auth0-angular/main/EXAMPLES.md | `## Step-Up Authentication` |
 | `@auth0/auth0-spa-js` (step-up) | https://raw.githubusercontent.com/auth0/auth0-spa-js/main/examples/step-up-authentication.md | whole file |
-| `@auth0/nextjs-auth0` | https://raw.githubusercontent.com/auth0/nextjs-auth0/main/EXAMPLES.md | `## Multi-Factor Authentication (MFA)` |
+| `@auth0/nextjs-auth0` | https://raw.githubusercontent.com/auth0/nextjs-auth0/main/guides/mfa.md | whole file |
 | `@auth0/auth0-auth-js` | https://raw.githubusercontent.com/auth0/auth0-auth-js/main/packages/auth0-auth-js/examples/mfa.md | whole file |
 | `@auth0/auth0-server-js` | https://raw.githubusercontent.com/auth0/auth0-auth-js/main/packages/auth0-server-js/MFA.md | whole file |
 | `Auth0.swift` (iOS/macOS) | https://raw.githubusercontent.com/auth0/Auth0.swift/master/examples/mfa-api.md | whole file |
@@ -243,6 +244,7 @@ which uses the `mfa_token` and the MFA API surface instead:
 | Trusting a frontend MFA check | The client can be bypassed entirely | Enforce server-side: `amr` on a web/session backend, the high-value scope on a resource API |
 | Checking `amr` on a resource API's access token | Access tokens carry no `amr` by default, so valid stepped-up callers are rejected | Gate the API on the high-value scope; add `amr` as a custom claim only if this API also validates it |
 | Hand-decoding the token to read `amr` (`jwt.decode`, `PyJWKClient`, `id_token.split`, manual JWKS) | Reinvents validation the SDK already performed, and usually disables `exp`/`iss`/audience checks in the process | Read `amr` from the SDK's session/current-user accessor; its claims are already verified |
+| Assuming the session accessor always carries `amr` | Some SDKs persist only a default claim subset, so `amr` is silently absent and the check never passes | Opt the claim in: `@auth0/nextjs-auth0` v4 needs a `beforeSessionSaved` hook to copy `amr` into the session (`session.user.amr`); `express-openid-connect` keeps the full claims on `req.oidc.idTokenClaims`, not the filtered `req.oidc.user` |
 | Omitting `max_age=0` on step-up | A still-valid session satisfies the request with no fresh challenge | Send `max_age=0` (or the SDK's fresh-auth option) for step-up |
 | Ignoring `mfa_required` from a silent token call | The step-up silently fails and the action proceeds unverified | Catch it and re-authenticate interactively |
 | Preferring SMS by default | SMS is vulnerable to SIM-swap | Prefer TOTP or WebAuthn; treat SMS as a fallback |
@@ -255,8 +257,9 @@ which uses the `mfa_token` and the MFA API surface instead:
 
 - **Tenant setup and Actions** - `tooling-cli` and `tooling-terraform` own Guardian
   factor/policy configuration and Action deployment (`auth0 actions ...`).
-- **SDK-side step-up trigger** - the detected `framework-*` reference owns the SDK's own
-  step-up call, its `mfa_required` handling, and any refresh-token requirement.
+- **SDK-side step-up trigger** - the SDK's own step-up call, its `mfa_required` handling,
+  and any refresh-token requirement live in that SDK's own example (see "Example code
+  snippets"), not in a `framework-*` reference.
 - **Server-side MFA enforcement** - the API `framework-*` references (JWT validation) own
   the scope/claim-check middleware; on a resource API gate the sensitive endpoint on the
   high-value scope (access tokens carry no `amr` by default), and on a web/session backend