In this guide, you’ll learn how to use Arcade to obtain user authorization and interact with third-party services by calling their API endpoints directly, without using Arcade for or definition. We’ll use Google’s Gmail API as an example to demonstrate how to:
Get authorization tokens through Arcade
Handle user authentication flows
Use tokens with external services
This can be useful when you need to manage authorization flows in your application.
Create a new file direct_api_call.py and import all libraries we’re going to use:
Python
from arcadepy import Arcadefrom google.oauth2.credentials import Credentialsfrom googleapiclient.discovery import build
JavaScript
Create a new file direct_api_call.js and import all libraries we’re going to use:
JavaScript
import { Arcade } from "@arcadeai/arcadejs";import { google } from "googleapis";
Initialize the Arcade client
Create an instance of the Arcade client:
PythonJavaScript
Python
Python
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
JavaScript
JavaScript
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
Initiate an authorization request
Use client.auth.start() to initiate the authorization process:
PythonJavaScript
Python
Python
# This would be your app's internal ID for the user (an email, UUID, etc.)user_id = "{arcade_user_id}"# Start the authorization processauth_response = client.auth.start(user_id=user_id,provider="google",scopes=["https://www.googleapis.com/auth/gmail.readonly"],)
JavaScript
JavaScript
// Your app's internal ID for the user (an email, UUID, etc).// It's used internally to identify your user in Arcade, not to identify with the Gmail service.// Use your Arcade account email for testing:const user_id = "{arcade_user_id}";// Start the authorization processlet auth_response = await client.auth.start(user_id, "google", { scopes: ["https://www.googleapis.com/auth/gmail.readonly"],});
Guide the user through authorization
If authorization is not completed, prompt the user to visit the authorization URL:
PythonJavaScript
Python
Python
if auth_response.status != "completed": print("Please complete the authorization challenge in your browser:") print(auth_response.url)
JavaScript
JavaScript
if (auth_response.status !== "completed") { console.log("Please complete the authorization challenge in your browser:"); console.log(auth_response.url);}
Wait for the user to authorize the request
PythonJavaScript
Python
Python
# Wait for the authorization to completeauth_response = client.auth.wait_for_completion(auth_response)
JavaScript
JavaScript
// Wait for the authorization to completeauth_response = await client.auth.waitForCompletion(auth_response);
Use the obtained token
Once authorization is complete, you can use the obtained token to access the third-party service:
For each item in the list/array, you could use the users.messages.get endpoint to get the full message details.
Consider using the Arcade Gmail MCP Server, which simplifies the process for retrieving email messages even further! The pattern described here is useful if you need to directly get a token to use with Google in other parts of your codebase.
How it works
By using client.auth.start and client.auth.wait_for_completion, you leverage Arcade to manage the OAuth flow for user authorization.
Arcade handles the authorization challenges and tokens, simplifying the process for you.
Next steps
Integrate this authorization flow into your application, and explore how you can manage different auth providers and scopes.