Arcade
Github Discord
BuildCall tools

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 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
bash npm install @arcadeai/arcadejs googleapis

Gradle:

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:

<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

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

Create a new file direct_api_call.js and import all libraries we’re going to use:

import { Arcade } from "@arcadeai/arcadejs";
import { google } from "googleapis";

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

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 :

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

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

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

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

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

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

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
if (auth_response.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(auth_response.url);
}
// 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

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
// Wait for the authorization to complete
auth_response = await client.auth.waitForCompletion(auth_response);
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:

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)

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);
// 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 python3 direct_api_call.py
javascript node direct_api_call.js

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:

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

Edit on GitHub

Last updated on

Handling errors

Learn how to handle errors when using tools with Arcade's Tool Development Kit (TDK)

Overview

Learn how to integrate Arcade tools into your custom applications with authentication and tool management

On this page

PrerequisitesInstall required librariesGradle:Maven:Start codingInitialize the Arcade clientInitiate an authorization requestGuide the user through authorizationWait for the user to authorize the requestUse the obtained tokenExecute the codeHow it worksNext steps