Add secure/brand auth in production doc #341
Draft
+129
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
evantahler
requested changes
Jul 10, 2025
|
|
||
| # Secure and Brand the Auth Flow in Production | ||
|
|
||
| To keep your users safe, Arcade.dev performs a session verification check when a tool is authorized for the first time. This check verifies that the user who is authorizing the tool is the same user who started the authorization flow, which helps prevent phishing attacks. |
There was a problem hiding this comment.
a session verification check
I like that phrasing a lot!
There was a problem hiding this comment.
@evantahler When I was building the UI, I ended up calling it "user verification" instead of "session verification". I think it's less jargony, what do you think?
There was a problem hiding this comment.
neutral - either way is good with me. But be consistent!
Comment on lines
23
to
29
| <Note> | ||
| Arcade's default OAuth apps can *only* be used with the Arcade session verifier. | ||
| If you are building a multi-user production app, you must obtain your own OAuth app credentials and add them to Arcade. | ||
| For example, [configure Google auth in the Arcade Dashboard](https://docs.arcade.dev/home/auth-providers/google#access-the-arcade-dashboard). | ||
| </Note> | ||
|
|
||
| The Arcade.dev session verifier helps keep your auth flows secure while you are building and testing your agent or app. When you're ready to share your work with others, implement a [custom session verifier](#set-up-a-custom-session-verifier) so your users don't need to sign in to Arcade.dev. |
There was a problem hiding this comment.
Switch the order of these 2 paragraphs
There was a problem hiding this comment.
The <Note> para and this para?
There was a problem hiding this comment.
I'd like the explanation of the session verifier to come first
|
|
||
| ## Set up a custom session verifier | ||
|
|
||
| In a production application or agent, user sessions are verified by your code, not Arcade.dev. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. |
There was a problem hiding this comment.
Suggested change
| In a production application or agent, user sessions are verified by your code, not Arcade.dev. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. | |
| In a production application or agent, user sessions are verified by your code, not Arcade.dev. This allows you to fully control your end-user's experience and authentication. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. |
|
|
||
| When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's session details. | ||
|
|
||
| If you need help, start a [GitHub discussion](https://github.com/ArcadeAI/arcade-ai/discussions) and we'll be happy to assist. |
There was a problem hiding this comment.
Pre-start the discussion now, and link that URL. One federated discussion is better so folks and help each other
| The route must gather the following information: | ||
|
|
||
| - The `flow_id` from the current URL's query string | ||
| - The unique ID of the user currently signed in. This varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. |
There was a problem hiding this comment.
Suggested change
| - The unique ID of the user currently signed in. This varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. | |
| - The unique ID of the user currently signed in. This varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. User IDs are commonly an ID from your application, email address, or similar. |
Comment on lines
+62
to
+75
| <Tabs items={["REST"]} storageKey="preferredLanguage"> | ||
| <Tabs.Tab> | ||
| ```text | ||
| POST https://cloud.arcade.dev/api/v1/oauth/confirm_user | ||
| Authorization: Bearer <arcade_api_key> | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "flow_id": "<flow_id from the query string>", | ||
| "user_id": "<the current user's ID>" | ||
| } | ||
| ``` | ||
| </Tabs.Tab> | ||
| </Tabs> |
There was a problem hiding this comment.
We will get this into the client libs soon, yes?
There was a problem hiding this comment.
Yes, next on my list. That will result in more tabs here
Comment on lines
+120
to
+121
| In the Arcade Dashboard, pick the **Custom verifier** option and add the URL of your verifier route. | ||
|
|
There was a problem hiding this comment.
TODO: Add screenshot soon
Co-authored-by: Evan Tahler <[email protected]>
…g-oauth-sec-docs' into nate/customer-facing-oauth-sec-docs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add a doc explaining how to configure session verification for production.