Directly call third-party APIs

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

Sign up for an Arcade if you haven’t already
Generate an Arcade API key and take note of it

Install required libraries

Python

bash pip install arcadepy google-api-python-client google-auth-httplib2 google-auth-oauthlib

JavaScript

bash npm install @arcadeai/arcadejs googleapis

Java

Gradle:

GROOVY


implementation("dev.arcade:arcade-java:${arcade-java-version}")
implementation("com.google.api-client:google-api-client:2.9.0")
implementation("com.google.oauth-client:google-oauth-client-jetty:1.39.0")
implementation("com.google.apis:google-api-services-gmail:v1-rev20260112-2.0.0")

Maven:

XML


<dependency>
    <groupId>dev.arcade</groupId>
    <artifactId>arcade-java</artifactId>
    <version>${arcade-java-version}</version>
</dependency>
<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>2.9.0</version>
</dependency>
<dependency>
    <groupId>com.google.oauth-client</groupId>
    <artifactId>google-oauth-client-jetty</artifactId>
    <version>1.39.0</version>
</dependency>
<dependency>
    <groupId>com.google.apis</groupId>
    <artifactId>google-api-services-gmail</artifactId>
    <version>v1-rev20260112-2.0.0</version>
</dependency>

See the Arcade Java SDK docs for the latest version.

Start coding

Python

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

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";

Java

Create a new file GmailExample.java and import all packages we’re going to use:

Java


import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.model.Message;
import dev.arcade.client.ArcadeClient;
import dev.arcade.client.okhttp.ArcadeOkHttpClient;
import dev.arcade.models.AuthorizationContext;
import dev.arcade.models.AuthorizationResponse;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

Initialize the Arcade client

Create an instance of the :

Python


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

JavaScript


const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable

Java


// Automatically finds the `ARCADE_API_KEY` env variable
ArcadeClient client = ArcadeOkHttpClient.fromEnv();

Initiate an authorization request

Python

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"],
)

JavaScript

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

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 process
let auth_response = await client.auth.start(user_id, "google", {
  scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
});

Java

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

Java


// 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:
String userId = "{arcade_user_id}";
 
AuthorizationResponse authResponse = client.auth().start( userId, "google", "oauth2",
  List.of("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)

JavaScript


if (auth_response.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(auth_response.url);
}

Java


// check the response status
authResponse
    .status()
    .filter(status -> status != AuthorizationResponse.Status.COMPLETED)
    .flatMap(status -> authResponse.url())
    .ifPresent(url -> logger.info("Click this link to authorize: {}", 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)

JavaScript


// Wait for the authorization to complete
auth_response = await client.auth.waitForCompletion(auth_response);

Java


AuthorizationResponse completedAuthResponse = client.auth().waitForCompletion(authResponse);

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)

JavaScript


const auth = new google.auth.OAuth2();
auth.setCredentials({ access_token: auth_response.context.token });
const gmail = google.gmail({ version: "v1", auth });
 
// List email messages
const response = await gmail.users.messages.list({
  userId: "me",
});
 
const email_messages = response.data.messages || [];
console.log(email_messages);

Java


// Use the credential
String token = completedAuthResponse.context().flatMap(AuthorizationContext::token).get();
 
JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
HttpTransport httpTransport = new NetHttpTransport();
GoogleCredential credential = new GoogleCredential().setAccessToken(token);
 
Gmail gmail = new Gmail.Builder(httpTransport, jsonFactory, credential)
        .setApplicationName("Your Application Name")
        .build();
 
// List email messages
List<Message> messages = gmail.users().messages().list("me").execute().getMessages();
logger.info("Messages: {}", messages);

Execute the code

Python

python python3 direct_api_call.py

JavaScript

javascript node direct_api_call.js

Java

Run the GmailExample.java class.

See the Arcade Java SDK Examples for the full class.

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 April 7, 2026

Handling errors Overview