From 4cda30a87ad2df4476a0d369d00c2c16254ab321 Mon Sep 17 00:00:00 2001
From: 0xFirekeeper <43042585+0xFirekeeper@users.noreply.github.com>
Date: Sat, 23 Aug 2025 00:37:20 +0000
Subject: [PATCH] Clarify authentication flows in wallet API docs (#7899)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated the documentation to distinguish between two-step authentication for email, phone, passkey, and SIWE, and single-step flows for guest, custom, and social authentication. Added details and endpoint references for each flow to improve clarity for API users.

<!-- start pr-codex -->

---

## PR-Codex overview
This PR updates the documentation for the authentication process in the `wallets` page, clarifying the steps for different authentication methods and introducing a new section on social authentication.

### Detailed summary
- Clarified the two-step authentication process for email, phone, passkey, or SIWE.
- Added information on skipping the first step for guest or custom authentication.
- Updated the description for initiating authentication to specify SIWE.
- Introduced a new section on social authentication, detailing a single-step flow.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **Documentation**
  * Clarified API Authentication flows: two-step for email, phone, passkey, or SIWE; skip-first-step option for guest or custom auth.
  * Updated headings and examples to reflect the revised two-step flow (initiate to get a challenge, then complete).
  * Added a Social Authentication section describing a single-step OAuth flow via a dedicated endpoint, with links to provider details and code samples.
  * Reorganized content so Get Wallet Information follows the updated authentication flows for better readability.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/portal/src/app/wallets/page.mdx | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/apps/portal/src/app/wallets/page.mdx b/apps/portal/src/app/wallets/page.mdx
index c5b869da205..b9fc983c05a 100644
--- a/apps/portal/src/app/wallets/page.mdx
+++ b/apps/portal/src/app/wallets/page.mdx
@@ -72,13 +72,14 @@ Create wallets for your users with flexible authentication options. Choose from
 
 ## API Authentication
 
-Authenticating a user is done in two steps:
+For email, phone, passkey, or SIWE authentication, a two-step process is used:
+- Initiate authentication to get a challenge
+- Complete authentication with the challenge response
 
-1. Initiate authentication
-2. Complete authentication
+For guest or custom (jwt/auth-payload) authentication, you can skip the first step and directly use the `/v1/auth/complete` endpoint with the required parameters.
 
 ### Initiate Authentication
-Start authentication with email, phone, passkey, or social providers
+Start authentication with email, phone, passkey, or SIWE
 
 <OpenApiEndpoint path="/v1/auth/initiate" method="POST" />
 
@@ -87,6 +88,15 @@ Verify and complete the authentication process:
 
 <OpenApiEndpoint path="/v1/auth/complete" method="POST" />
 
+## Social Authentication
+
+### Single Step Flow
+OAuth is done in a single step using a dedicated endpoint.
+
+Visit the API reference for more details on the available social providers and code snippets.
+
+<OpenApiEndpoint path="/v1/auth/social" method="GET" />
+
 ### Get Wallet Information
 Retrieve authenticated user's wallet details: