Calling Tools with Authentication

Initialize the client

Import the Arcade AI client in a Python script. The client automatically finds API keys set by arcade login.

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

Authorize a tool directly

Many tools require authorization. For example, the Google.GetEmails tool requires authorization with Google.

This authorization must be approved by the user. By approving, the user allows your agent or app to access only the data they've approved.

# As the developer, you must identify the user you're authorizing
# and pass a unique identifier for them (e.g. an email or user ID) to Arcade:
THE_USER_ID = "[email protected]"
 
# Request access to the user's Gmail account
auth_response = client.tools.authorize(
    tool_name="Google.GetEmails",
    user_id=THE_USER_ID,
)
 
print(f"Click this link to authorize: {auth_response.authorization_url}")

This will print a URL that the user must visit to approve the authorization.

Check for authorization status

It may take a few minutes for the user to approve the authorization.

Use the client.auth.wait_for_completion() method to wait for the authorization to complete:

auth_response = client.auth.wait_for_completion(auth_response)

Call the tool with authorization

Once the user has approved the action, you can run the tool. You only need to pass the user_id:

emails_response = client.tools.execute(
    tool_name="Google.GetEmails",
    user_id=MY_USER_ID,
)
print(emails_response)

How it works

When you call a tool with client.tools.execute(), Arcade AI:

1. Checks for authorization.
2. Routes the request to the tool's provider.
3. Returns the tool's response.

With client.tools.authorize(), you can also authorize tools for later use.

These APIs give you programmatic control over tool calling. If you just want to integrate tools into an LLM workflow, see Call tools with LLMs.