Auth0 Documentation Audit

Auth0's docs are broad and genuinely agent-first (root llms.txt, full-content files, MCP servers, OpenAPI) and largely accurate — but they carry a self-contradicting deprecation deadline, a dead link in the very file agents are told to read first, two products colliding under one name, and several high-stakes caveats buried as unflagged prose.

1. Rules & Hooks end-of-life date contradicts itself by two years (critical)

Location: https://auth0.com/docs/customize/rules vs. the linked blog post https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/

Problem: The Rules documentation states: "The End of Life (EOL) date of Rules and Hooks will be November 18, 2026." The official EOL blog post that the same docs page links to states: "Rules and Hooks will be removed from all tenants on November 18, 2024." That is a two-year discrepancy on a hard removal deadline, and the docs page explicitly links out to the blog post as its authoritative reference. Compounding the confusion, the docs page's retention sentence reads "Existing tenants with active Hooks will retain Hooks product access through end of life" — it names only Hooks, leaving tenants that still run Rules with no explicit retention statement on a page titled and scoped to Rules.

Consequence: A developer (or an agent) planning a migration off Rules/Hooks cannot determine when their authentication extensibility code stops running. Trusting the docs page (2026) when the blog says removal already passed (2024) means production login flows could break with no runway — and Rules-only tenants get no clear statement about whether they're covered at all.

The fix: Reconcile the date to a single source of truth and update both the docs page and the blog post. If removal already occurred, the docs page must say so unambiguously instead of stating a future 2026 date. Add an explicit retention statement that covers Rules, not just Hooks.

2. Canonical llms.txt links the Auth0 MCP Server to a 404 (critical)

Location: https://auth0.com/llms.txt → "Developer Tools" → https://auth0.com/docs/customize/integrations/ai-tools/auth0-mcp-server

Problem: The root llms.txt — the file Auth0 explicitly tells every AI agent to fetch first — lists the "Auth0 MCP Server" at /docs/customize/integrations/ai-tools/auth0-mcp-server, which returns HTTP 404 on repeated fetches. The live page is at /docs/get-started/auth0-mcp-server (HTTP 200, confirmed). This is the one link from the index that was probed and found dead; the other links in the file were not all individually verified.

Consequence: An agent following the canonical index to set up Auth0's own tenant-management MCP server hits a dead end on the one tool that connects agents to a tenant. The failure is silent for an agent — it gets a 404 page, not a redirect — so it cannot self-correct to the working URL (though an agent that already found the separate docs-search MCP server could fall back to searching for the right path).

The fix: Update the llms.txt "Developer Tools" entry to point at https://auth0.com/docs/get-started/auth0-mcp-server, and add a 301 redirect from the old path so existing bookmarks/agent caches resolve.

3. Two different products are both branded "MCP Server" (significant)

Location: https://auth0.com/docs/get-started/auth0-mcp-server and https://auth0.com/docs/get-started/build-with-ai-tools (→ https://auth0.com/docs/mcp)

Problem: The "Auth0 MCP Server" connects agents to a tenant to "create applications, manage users, or deploy Actions." A separate "Auth0 Docs MCP Server" (server URL https://auth0.com/docs/mcp, HTTP transport) only "exposes the SearchAuth0Docs tool" to search documentation. Two distinct products with different URLs, transports, and capabilities share the "MCP Server" name.

Consequence: A developer wiring up an MCP client cannot tell from the name alone which server manages their tenant versus which one just searches docs. Pointing a Claude Desktop / Cursor / Windsurf config at the wrong one yields a tool surface that can't do what the user expects, with no obvious error explaining why.

The fix: Disambiguate the names everywhere they appear — e.g., "Auth0 Management MCP Server" vs. "Auth0 Docs Search MCP Server" — and add a one-line comparison table (purpose, URL, transport) on both pages.

4. Free-plan users silently cannot open support tickets — buried on the API error page (significant)

Location: https://auth0.com/docs/api/authentication → "Errors" and "Support"

Problem: The error guidance funnels developers toward support ("In any other case you can use our support options"; "If you have problems or need help with your case, you can always reach out to our Support"), but the access restriction is tucked into the last sentence of the Support section as plain prose: "if you have a free subscription plan, and you are not in your 22-day trial period, you will not be able to access or open tickets in the Support Center. In this case, you can seek support through the Auth0 Community." It is not flagged as a callout, and it sits below the advice that sends the reader to support in the first place.

Consequence: A free-tier developer hitting a production auth error follows the page's own instructions to "reach out to Support," only to discover at the support form that they cannot open a ticket — mid-incident, with no signal earlier on the page. The actual fallback (Auth0 Community) is buried in the same sentence and easy to miss; an agent skimming for the support path will surface a route the user can't actually use.

The fix: Promote the free-plan restriction to a flagged note positioned before the "use our support options" line, and state the Community fallback up front so the supported path matches the reader's plan.

5. Authentication API documents no enumerated error codes (significant)

Location: https://auth0.com/docs/api/authentication → "Errors"

Problem: The entire error contract is: "If you get an 4xx HTTP response code, then you can assume that there is a bad request from your end. 5xx errors suggest a problem on Auth0's end." No specific error codes, no error/error_description value enumeration, no mapping of which endpoint returns which error. The page admits error objects "contain an error code and an error description" but never lists any.

Consequence: Developers can't write deterministic error handling, and agents — which can't apply human judgment — fail silently when they hit an error string that isn't documented anywhere. "It's a 4xx, it's your fault" is not a parseable contract.

The fix: Publish an enumerated error reference (code, description, HTTP status, triggering condition) as a structured table, ideally backed by the OpenAPI spec — instead of the 4xx/5xx split.

6. Refresh-token blocker on browser POSTs is buried as unflagged prose (significant)

Location: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow → "How to implement"

Problem: The security-critical exception — "If a browser application, with an Origin header, makes a POST request to the /oauth/token endpoint, Auth0 doesn't issue refresh tokens, even if the application has Allow Refresh Token Rotation enabled and sends the offline_access scope" — appears as the last plain paragraph of the section, with no callout, warning box, or heading.

Consequence: A developer who enabled rotation and offline_access and still gets no refresh token has no signal that this is expected behavior. They'll burn time debugging their config for a documented-but-hidden platform rule, and agents skimming for the happy path will miss it entirely.

The fix: Promote this to a flagged warning/admonition near the top of the implementation section, and cross-link it from the refresh-tokens page.

7. The /troubleshoot page contains no troubleshooting guidance (minor)

Location: https://auth0.com/docs/troubleshoot

Problem: The page lives at the /troubleshoot URL but is titled "Auth0 Platform" and contains only "Customer Support," "Account and Plan Management," "Operational Policies," and "Product Lifecycle" — support tiers, billing, and policy links. There is no error guidance, no debugging steps, no common-failure reference. The content itself is useful; the defect is that the URL and title promise debugging help and deliver account administration.

Consequence: A developer who hits an auth error and navigates to (or is linked to) /troubleshoot lands on account-management content and finds nothing to debug with — an information-architecture mismatch between the path's promise and its contents.

The fix: Either repurpose /troubleshoot into an actual error/debugging hub (common errors, log analysis, flow-specific failures) or rename/redirect it to match its real content (e.g., /platform).

8. The bare filename "llms-full.txt" refers to two different-scope files (minor)

Location: https://auth0.com/llms.txt vs. https://auth0.com/docs/get-started/build-with-ai-tools

Problem: The root llms.txt deliberately lists two distinct full-content artifacts: https://auth0.com/llms-full.txt under "Full Content" ("Complete content of all Auth0 product pages, pricing, and agent experience data" — whole-site), and https://auth0.com/docs/llms-full.txt under "Auth0 docs" ("Full Documentation Content" — docs-only). These are not a contradiction; they are two files at two scopes. The friction is naming: the build-with-ai-tools LLM-context table refers to the docs-scoped file by the bare filename llms-full.txt (URL https://auth0.com/docs/llms-full.txt, "Full content of all articles"), while the root file reserves that same bare filename for the whole-site file.

Consequence: An agent that keys on the bare filename llms-full.txt rather than the full path can conflate the docs-only file with the whole-site file — ingesting the wrong scope (and either missing product/pricing content or pulling more than intended). The ambiguity is in the labeling, not the URLs.

The fix: Give the two files distinct, self-describing labels wherever they're referenced (e.g., "Full Site Content" vs. "Full Docs Content") and always cite the complete path, so an agent never has to disambiguate from the filename alone.

9. Changelog uses overlapping, undefined release-stage labels (minor)

Location: https://auth0.com/changelog/llms.txt

Problem: Release entries mix "Beta," "Early Access (EA)," "Open Early Access," and "Generally Available (GA)" — e.g., "now in Beta," "is Early Access," "in Open Early Access," "now Generally Available" — without a consistent stage vocabulary on the index, and "Early Access" vs. "Open Early Access" are not differentiated inline.

Consequence: A developer deciding whether to adopt a feature can't infer stability or support guarantees from the label alone, because the stages overlap and aren't defined where they're used. Agents summarizing release readiness will mislabel maturity.

The fix: Define the lifecycle stages once (with support/SLA implications), link each changelog label to that definition, and collapse "Early Access" vs. "Open Early Access" into a single documented meaning.

10. Pricing table shows unexplained "Not available" gaps for the Professional plan (minor)

Location: https://auth0.com/pricing.md → "B2C Base Price by MAUs"

Problem: In the B2C base-price table, Professional reads "Contact us" at 30,000 MAUs and "Not available" at 40,000 and 50,000 MAUs, while Essentials lists explicit prices ($2,800, $3,500) at those same tiers. The Notes block on the page explains yearly billing, enterprise custom pricing, and the Free plan — but says nothing about why a higher-tier plan reads "Not available" at MAU counts a cheaper plan still serves.

Consequence: This is an agent-facing pricing doc; a model estimating cost for ~40k–50k MAUs on Professional gets "Not available" with no rule to interpret it, and may wrongly conclude the plan can't serve that volume (when it likely means "contact sales"). Humans hit the same dead end.

The fix: Replace "Not available" with the actual behavior (e.g., "Contact sales for 40k+ MAUs") and add a note explaining the gap, so the table is self-describing for automated parsing.

11. GitHub docs repo sends mixed signals about whether docs are open-source (minor)

Location: https://github.com/auth0/docs (README and CONTRIBUTING)

Problem: The README states most content "is no longer hosted on GitHub and therefore no longer open-source" and "is not the source of content at https://auth0.com/docs," yet the repo stays public and invites "Pull requests and issues for Quickstarts." Meanwhile the docs index advertises "sample code, articles, tutorials, and API reference." CONTRIBUTING adds that quickstart data "comes directly from the docs API at /meta/quickstart," which is "for Auth0 internal use only" with "NO SLA or support."

Consequence: An outside contributor wanting to fix a doc error can't tell what's editable here versus what lives in an internal CMS, and may open a PR against content that no longer flows to the live site. Effort gets wasted on a repo that's authoritative for only a slice of the docs.

The fix: Add a clear "what's editable here vs. elsewhere" matrix at the top of the README, and explicitly scope issues/PRs to quickstarts so contributors don't target deprecated content.

12. Outdated "@auth0status on Twitter" reference in the API error guidance (minor)

Location: https://auth0.com/docs/api/authentication → "Errors"

Problem: For 5xx errors the docs say to "check Auth0 Status Page and @auth0status on Twitter." Twitter is now X, and the handle is presented as the recommended channel for live incident status.

Consequence: Minor on its own, but it's the path a developer follows mid-incident to confirm whether an outage is Auth0's fault. Stale platform branding in an incident-response instruction erodes trust in the rest of the error guidance.

The fix: Update to current branding/handle (or drop the social reference and link only the status page), and verify the handle still exists.

What they do well

• Genuinely agent-first indexing: root llms.txt, full-content files, per-product .md files, a docs-search MCP server, and a tenant-management MCP server — Auth0 clearly designed for AI-agent consumption, which is rare.
• Structured, parseable Management API details: documents both pagination schemes with explicit per_page/take maximums (50 Public Cloud / 100 Private Cloud) and a 24-hour checkpoint expiry — though the OpenAPI v3.1 schema support those docs follow is itself still flagged "in Beta," so treat the machine-readable spec as not-yet-stable.
• Clear, well-sequenced flow walkthroughs: the Authorization Code Flow and the quickstart structure (Native / SPA / Web / Backend / AI Agent) give developers an obvious on-ramp by app type.

Top 3 recommendations

1. Resolve the Rules & Hooks EOL date to one correct value across the docs page and the blog post it links to — this is a production-breaking deadline that currently disagrees with itself by two years — and add a retention statement that covers Rules, not just Hooks.
2. Fix the llms.txt MCP Server link (404 → live URL) and add a redirect, since this is the dead link found in the file every agent is told to read first.
3. Give the Authentication API a real error reference (enumerated codes, not just 4xx/5xx), surface the free-plan support-ticket restriction before you point developers at Support, and disambiguate the two "MCP Server" products so both humans and agents can build deterministic integrations.