Direct Third-Party API Call
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 tool execution 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.
Prerequisites
- Sign up for an Arcade account if you haven’t already
- Generate an Arcade API key and take note of it
Install required libraries
pip install arcadepy google-api-python-client google-auth-httplib2 google-auth-oauthlib
Start coding
Create a new file direct_api_call.py
and import all libraries we’re going to use:
from arcadepy import Arcade
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
Initialize the Arcade client
Create an instance of the Arcade client:
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
Initiate an authorization request
Use client.auth.start
to initiate the authorization process:
# This would be your app's internal ID for the user (an email, UUID, etc.)
user_id = "[email protected]"
# Start the authorization process
auth_response = client.auth.start(
user_id=user_id,
provider="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:
if auth_response.status != "completed":
print("Please complete the authorization challenge in your browser:")
print(auth_response.url)
Wait for the user to authorize the request
auth_response = client.auth.wait_for_completion(auth_response)
Use the obtained token
Once authorization is complete, you can use the obtained token to access the third-party service:
credentials = Credentials(auth_response.context.token)
gmail = build("gmail", "v1", credentials=credentials)
email_messages = (
gmail.users().messages().list(userId="me").execute().get("messages", [])
)
print(email_messages)
Execute the code
python3 direct_api_call.py
You should see an output similar to this:, which is a list of the email messages returned by the Gmail API:
[{'id': '195f77a8ce90f2c1', 'threadId': '195f77a8ce90f2c1'}, {'id': '195ed467a90e8538', 'threadId': '195ed467a90e8538'}, ...]
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 Google toolkit, 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.