Skip to Content
HomeAuthorizationDirect Third-Party API Call

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 execution or definition. We’ll use Google’s Gmail API as an example to demonstrate how to:

  • Get authorization tokens through Arcade
  • Handle authentication flows
  • Use tokens with external services

This can be useful when you need to manage authorization flows in your application.

Prerequisites

Install required libraries

bash 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:

Python
from arcadepy import Arcade from google.oauth2.credentials import Credentials from googleapiclient.discovery import build

Initialize the Arcade client

Create an instance of the :

Python
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable

Initiate an authorization request

Use client.auth.start() to initiate the authorization process:

Python
# This would be your app's internal ID for the user (an email, UUID, etc.) user_id = "{arcade_user_id}" # 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 to visit the authorization URL:

Python
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

Python
# Wait for the authorization to complete 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:

Python
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

python 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:

TEXT
[{'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 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 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.

Last updated on