[DOC] Add Passkey Docs

[KaveeshaPiumini]

Purpose

This pull request adds comprehensive documentation for configuring and using passkeys (WebAuthn-based passwordless authentication) with Thunder. The new guide covers multiple integration approaches, including the hosted UI, atomic APIs, and flow-based APIs, and provides step-by-step instructions, sample API calls, and troubleshooting tips.

New documentation: Passkeys integration guide
The most important changes are:

Passkeys overview and prerequisites:

• Introduces passkeys as a phishing-resistant, passwordless authentication method using the WebAuthn standard, and explains their benefits and supported approaches in Thunder.
• Lists necessary prerequisites, such as HTTPS, allowed origins configuration, browser compatibility, and user provisioning requirements.

Integration approaches:

• Details three integration methods:
  • Thunder Gate (Hosted UI): Explains how to enable passkeys using Thunder’s out-of-the-box authentication pages, including flow configuration and OAuth2 integration steps.
  • Atomic API approach: Provides step-by-step instructions and example API calls for direct passkey registration and authentication using /register/passkey/* and /auth/passkey/* endpoints.
  • Flow-based approach: Describes how to use passkeys within orchestrated authentication/registration flows via /flow/execute, including handling WebAuthn ceremonies and flow steps. (F3f979

Related Issues

• Add Passkey-Based Authentication #610
• [DOC] Add Passkey Documentation #1339

Related PRs

• N/A

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified.
• Documentation provided. (Add links if there are any)
• Tests provided. (Add links if there are any)
  • Unit Tests
  • Integration Tests
• Breaking changes. (Fill if applicable)
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

Summary by CodeRabbit

• Documentation
  • Added comprehensive authentication guide documenting passwordless authentication using passkeys.
  • Covers integration approaches, WebAuthn ceremony steps, prerequisites, and detailed usage instructions.
  • Includes troubleshooting guidance for common implementation issues.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request adds comprehensive documentation infrastructure for passwordless authentication using passkeys. It includes navigation category files for documentation organization, vocabulary entries for spell-checking, and a detailed guide covering WebAuthn integration approaches (Thunder Gate, Atomic API, Flow/Execute).

Changes

Cohort / File(s)	Summary
Documentation Infrastructure docs/content/guides/authentication/_category_.json, docs/content/guides/authentication/passwordless-authentication/_category_.json	Added navigation category configuration files for organizing passwordless authentication documentation sections with positioning and collapsible options.
Vocabulary Configuration .vale/styles/config/vocabularies/vocab/accept.txt	Added 5 new vocabulary entries ([Pp]asswordless, APIs, UIs, iCloud, hostname) to expand spell-check acceptance patterns.
Passwordless Authentication Guide docs/content/guides/authentication/passwordless-authentication/passkeys.mdx	Added comprehensive documentation covering passkey-based passwordless authentication, including overview, integration approaches, WebAuthn ceremony steps, prerequisites, and implementation examples for multiple integration methods.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• DonOmalVindula
• ThaminduDilshan
• jeradrutnam

Poem

🐰 No passwords needed now, just a key so divine,
Passkeys and WebAuthn make the authentication line,
With Thunder Gate and Atomic flows, security's designed,
A hoppy guide for all to see, authentication refined! 🔐

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[DOC] Add Passkey Docs' clearly and concisely summarizes the main change: adding documentation for passkeys, which aligns with the comprehensive passkey documentation content added to the repository.
Description check	✅ Passed	The PR description provides a comprehensive Purpose section detailing what is being added, includes Related Issues links, and contains the full Checklist and Security checks from the template, meeting all required sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/content/guides/passkeys.mdx`:
- Around line 25-27: Replace the incorrect phrase "Both approaches follow the
WebAuthn standard ceremony:" with "All approaches follow the WebAuthn standard
ceremony:" in the paragraph that introduces the three WebAuthn approaches (the
line starting with "Both approaches follow the WebAuthn standard ceremony:"), so
the text correctly references all listed approaches.

[Copilot]

Pull request overview

Adds a new documentation guide explaining how to configure and use passkeys (WebAuthn) with Thunder across Hosted UI (Thunder Gate), Atomic APIs, and flow-based (/flow/execute) integrations.

Changes:

• Introduces a new Passkeys guide covering prerequisites, configuration, and integration options.
• Provides curl examples for atomic passkey registration/authentication endpoints.
• Documents how to use passkeys in orchestrated flows via /flow/execute, plus troubleshooting tips.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.74%. Comparing base (a634749) to head (45162fa).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1333   +/-   ##
=======================================
  Coverage   89.74%   89.74%           
=======================================
  Files         638      638           
  Lines       42021    42021           
  Branches     2424     2424           
=======================================
  Hits        37710    37710           
  Misses       2339     2339           
  Partials     1972     1972           

Flag	Coverage Δ
backend-integration-postgres	53.50% <ø> (ø)
backend-integration-sqlite	53.47% <ø> (ø)
backend-unit	82.26% <ø> (ø)
frontend-apps-develop-unit	90.63% <ø> (ø)
frontend-apps-gate-unit	84.88% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@docs/content/guides/passkeys.mdx`:
- Around line 171-251: Replace the phrase "not practical" with "impractical" in
the Registration with flow/execute section where the note starts with "Reminder:
Calling `/flow/execute`..." (search for the sentence containing "Calling
`/flow/execute` with a flow that only runs the passkey registration executor is
not practical") to tighten wording and match the style guide.
- Around line 29-43: Fix the grammar in the prerequisites bullet that reads "Use
a WebAuthn-capable browser (recent Chrome, Edge, Safari, or Firefox); You can
confirm support..." by making the clause after the semicolon lowercase ("you")
or by splitting into two sentences; update the sentence in
docs/content/guides/passkeys.mdx (look for the "Use a WebAuthn-capable browser"
bullet) so it becomes either "... Firefox); you can confirm support..." or "...
Firefox. You can confirm support..." to correct punctuation and capitalization.
- Around line 80-170: The OpenAPI spec in api/authentication.yaml uses the wrong
paths "/auth/webauthn/start" and "/auth/webauthn/finish"; update those path keys
to "/auth/passkey/start" and "/auth/passkey/finish" so the spec matches the
implemented endpoints and the docs in guides/passkeys.mdx (registration paths in
api/registration.yaml are already correct). Ensure any references/operationIds
that assume the old path are updated consistently to the new "/auth/passkey/*"
paths.

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@docs/content/guides/passkeys.mdx`:
- Around line 29-43: Add a new "Assumptions" section immediately above the
existing "Prerequisites" heading in docs/content/guides/passkeys.mdx that
briefly lists the document's preconditions (e.g., the UI is served over HTTPS
with an RP ID-matching hostname, you have access to deployment config to add
allowed origins, users exist or can be provisioned in Thunder, and the reader is
using a WebAuthn-capable browser). Keep it short (one paragraph or bullet list)
and clearly labeled "Assumptions" so readers see these environment/context
requirements before the "Prerequisites" section.
- Around line 80-83: Update the headings in this MDX to Title Case (preserve the
existing heading levels/MDX hashes) — specifically change "Use Passkey Atomic
API in your app" to "Use Passkey Atomic API in Your App", "Registration flow" to
"Registration Flow" and apply the same Title Case fix to the other failing
headings referenced (the ones around the other ranges) so Vale lint passes; keep
the heading markers (##, ###) and surrounding content unchanged.
- Around line 254-258: Add a short "Next steps" section at the end of the
passkeys guide (file docs/content/guides/passkeys.mdx) that summarizes remaining
setup tasks and links to related docs; specifically include items to verify
allowed_origins and RP ID, ensure HTTPS for production, use the most recent
sessionToken for ceremonies, adjust authenticatorSelection for platform vs
roaming authenticators, and confirm the user exists (or note usernameless
flows), plus links to relevant reference pages or examples so readers know what
to do after finishing the guide.
- Around line 63-67: Replace the user-facing term "login" with "sign-in" in the
passkeys doc: change the bullet "Rendering login/registration prompts based on
the configured flow" to use "sign-in/registration prompts" (the phrase to update
is "Rendering login/registration prompts"), keep system-level uses of "login"
like "social login" untouched.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.vale/styles/config/vocabularies/vocab/accept.txt:
- Around line 15-19: Add the token "usernameless" to the accepted vocabulary
file so Vale stops flagging it; update the vocab list in accept.txt by inserting
either "usernameless" (and/or a case-insensitive pattern like "[Uu]sernameless")
alongside the other entries (e.g., near "[Pp]asswordless") so the lint rules
recognize the term used in passkeys.mdx.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.