Clarify authentication flows in wallet API docs #7899
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
4 Skipped Deployments
|
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. |
WalkthroughDocumentation updates to the wallets page clarifying authentication: two-step challenge/response for email, phone, passkey, or SIWE; guests/custom (jwt/auth-payload) may skip initiation and call /v1/auth/complete directly; added single-step Social Authentication via GET /v1/auth/social. Headings and notes adjusted. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as Auth API
note over Client,API: Two-step flow (Email/Phone/Passkey/SIWE)
Client->>API: POST /v1/auth/initiate (identifier/method)
API-->>Client: 200 { challenge, challengeId, ... }
Client->>API: POST /v1/auth/complete (challengeId, response)
API-->>Client: 200 { session, wallet, ... }
opt Skip init (Guest/Custom jwt/auth-payload)
note over Client,API: Guest/Custom can directly complete
Client->>API: POST /v1/auth/complete (required params)
API-->>Client: 200 { session, wallet, ... }
end
sequenceDiagram
autonumber
actor Client
participant API as Auth API
participant OAuth as OAuth Provider
note over Client,API: Social Authentication (single step)
Client->>API: GET /v1/auth/social?provider=...&redirect_uri=...
API->>OAuth: Initiate OAuth (authorize)
OAuth-->>Client: Redirect / callback
Client->>API: Callback hit (provider code/state)
API-->>Client: 200 { session, wallet, ... }
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes ✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
added
the
Portal
0xFirekeeper
added
merge-queue
Merge activity
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #7899 +/- ##
=======================================
Coverage 56.53% 56.53%
=======================================
Files 904 904
Lines 58592 58592
Branches 4143 4143
=======================================
Hits 33126 33126
Misses 25360 25360
Partials 106 106
🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
apps/portal/src/app/wallets/page.mdx (3)
75-77: Clarify the “challenge” per method (OTP vs WebAuthn vs SIWE nonce).Right now “challenge” is generic. Being explicit reduces confusion and support load.
-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 +For email, phone, passkey, or SIWE authentication, a two-step process is used: +- Initiate authentication to get a challenge: + - email/phone → one-time code (OTP) + - passkeys → WebAuthn challenge + - SIWE → nonce in the SIWE message +- Complete authentication by returning the appropriate response: + - OTP code + - WebAuthn assertion + - SIWE signature (over the provided nonce)
82-82: Minor copy/grammar: pluralize “passkeys” and add terminal punctuation.Also aligns with static analysis hint.
-Start authentication with email, phone, passkey, or SIWE +Start authentication with email, phone, passkeys, or SIWE.
75-82: Consistency with intro and related guides.Top-of-page line 37 mentions “social OAuth” while the two-step list here excludes “social” and the Initiate section title removed it. Confirm that social providers are only via the single-step endpoint and not via
/v1/auth/initiate; if so, consider a brief note here linking to the Social section to prevent skimming confusion.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
apps/portal/src/app/wallets/page.mdx(2 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
PR: thirdweb-dev/js#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-18T19:19:55.613Z
Learning: Applies to packages/thirdweb/src/wallets/** : Support for in-app wallets (social/email login)
🪛 LanguageTool
apps/portal/src/app/wallets/page.mdx
[grammar] ~81-~81: There might be a mistake here.
Context: ...parameters. ### Initiate Authentication Start authentication with email, phone, ...
(QB_NEW_EN)
[grammar] ~93-~93: There might be a mistake here.
Context: ...ial Authentication ### Single Step Flow OAuth is done in a single step using a d...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: E2E Tests (pnpm, esbuild)
- GitHub Check: E2E Tests (pnpm, vite)
- GitHub Check: E2E Tests (pnpm, webpack)
- GitHub Check: Size
- GitHub Check: Unit Tests
- GitHub Check: Build Packages
- GitHub Check: Lint Packages
- GitHub Check: Analyze (javascript)
🔇 Additional comments (2)
apps/portal/src/app/wallets/page.mdx (2)
91-99: Verify HTTP method and document query parameters for/v1/auth/socialI didn’t find any route or OpenAPI definitions for this endpoint in the repo, so please confirm the actual HTTP method (GET vs. POST) and surface all required query parameters in the docs to ensure accuracy.
• File:
apps/portal/src/app/wallets/page.mdx(lines 91–99)Suggested diff to mark this TODO and update once you’ve verified:
## Social Authentication ### Single-step flow OAuth is performed in a single step using a dedicated endpoint. -<OpenApiEndpoint path="/v1/auth/social" method="GET" /> +<!-- TODO: confirm HTTP method and list required query parameters for social OAuth --> +<OpenApiEndpoint path="/v1/auth/social" method="<METHOD>" />Once verified, replace
<METHOD>with the real HTTP verb and add a params list, for example:
provider(e.g.apple,discord, …)redirect_uri(must match the allow-listed URI)state(CSRF protection value)code(OAuth code returned by provider)code_verifier(for PKCE, if applicable)
79-79: Clarify request bodies for guest and custom flowsThe generic MDX snippet currently says “guest or custom (jwt/auth-payload)” but doesn’t show the exact request schemas. Please expand it to list each valid payload for
/v1/auth/complete:- 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. + For guest or custom flows, skip Step 1 and POST to `/v1/auth/complete` with one of: + + ```json + // Guest (no credentials required) + { "type": "guest" } + + // Custom—JWT issued by your server + { "type": "jwt", "payload": "<your-jwt>" } + + // Custom—server-signed payload + signature + { "type": "auth-payload", "payload": "<your-auth-payload>" } + ``` + + See the API reference for full request schemas and error codes.Please verify these field names and object shapes against the live OpenAPI spec for
/v1/auth/complete.
size-limit report 📦
|
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 -->
graphite-app
bot
force-pushed
the
firekeeper/oauth
branch
from
175aeea to
4cda30a
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
apps/portal/src/app/wallets/page.mdx (4)
75-77: Clear separation of two-step flow; consider ordered steps and SIWE contextThe clarification reads well. Minor UX copy tweak: use an ordered list and hint what the “challenge” is across methods to reduce ambiguity.
-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 +For email, phone, passkey, or SIWE authentication, use a two-step flow: +1. Initiate authentication to get a challenge (e.g., OTP, passkey request, or SIWE nonce). +2. Complete authentication with the challenge response.
79-79: Tighten wording; capitalize JWT; reference the step explicitlyConsistent casing and explicit “step 1” reference improves scannability.
I can add a concise example of the exact parameters accepted by /v1/auth/complete for guest/custom if you confirm the fields.
-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. +For guest or custom (JWT/auth-payload) authentication, you can skip step 1 and call the `/v1/auth/complete` endpoint directly with the required parameters.
82-82: Micro copyedit for readability (addresses grammar hint)Minor preposition tweak.
-Start authentication with email, phone, passkey, or SIWE +Start authentication for email, phone, passkey, or SIWE.
91-99: Social auth section: hyphenation, clarify behavior, and verify HTTP method
- Style: “Single‑step flow” is the conventional hyphenation (also satisfies grammar hint).
- Behavior: Is this endpoint initiating a redirect (authorization request) or returning tokens directly? If it redirects, consider adding a one‑liner about configuring redirect/callback URLs.
- Method: Using GET for an auth-completing endpoint can be correct if it’s initiating OAuth (authorization endpoint), but unusual if it exchanges codes/tokens. Please confirm the intended semantics in the API reference.
Happy to add a short Callout explaining redirect/callback configuration and a minimal sequence diagram if you confirm the flow.
-## Social Authentication +## Social Authentication -### Single Step Flow -OAuth is done in a single step using a dedicated endpoint. +### Single-step flow +Social OAuth completes in a single step via a dedicated endpoint. + +<Callout variant="info" title="Redirect & callback"> +Depending on the provider, this endpoint may initiate a redirect-based flow. Ensure your callback/redirect URL is configured in the dashboard. +</Callout> -Visit the API reference for more details on the available social providers and code snippets. +Visit the API reference for the list of supported providers and code snippets. -<OpenApiEndpoint path="/v1/auth/social" method="GET" /> +<OpenApiEndpoint path="/v1/auth/social" method="GET" />To double-check the method and expected behavior, I can incorporate a direct link if you share the canonical API reference path for this endpoint.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
apps/portal/src/app/wallets/page.mdx(2 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
PR: thirdweb-dev/js#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-18T19:19:55.613Z
Learning: Applies to packages/thirdweb/src/wallets/** : Support for in-app wallets (social/email login)
🪛 LanguageTool
apps/portal/src/app/wallets/page.mdx
[grammar] ~81-~81: There might be a mistake here.
Context: ...parameters. ### Initiate Authentication Start authentication with email, phone, ...
(QB_NEW_EN)
[grammar] ~93-~93: There might be a mistake here.
Context: ...ial Authentication ### Single Step Flow OAuth is done in a single step using a d...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: E2E Tests (pnpm, esbuild)
- GitHub Check: Size
- GitHub Check: Build Packages
- GitHub Check: E2E Tests (pnpm, vite)
- GitHub Check: Unit Tests
- GitHub Check: E2E Tests (pnpm, webpack)
- GitHub Check: Lint Packages
- GitHub Check: Analyze (javascript)
graphite-app
bot
removed
the
merge-queue
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.
PR-Codex overview
This PR updates the API Authentication documentation to clarify the authentication processes, including a new section on social authentication.
Detailed summary
Social Authenticationwith a single-step flow.Summary by CodeRabbit