---
title: "Authorized Tool Calling"
description: "Guide on calling tools that require authorization"
---

# Authorized Tool Calling

Arcade provides an authorization system that handles OAuth 2.0, API keys, and user tokens needed by AI agents to access external services through tools. This means your AI agents can now act on behalf of users securely and privately.

With Arcade, developers can now create agents that can as _as the end user of their application_ to perform tasks like:

- Creating a new Zoom meeting
- Sending or reading email
- Answering questions about files in Google Drive.

Arcade also allows for actions (tools) to be authorized directly. For example, to access a user's Gmail account, you can utilize the following guide.

import { Steps, Tabs, Callout } from "nextra/components";

<Steps>

### Initialize the client

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

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>
```python
from arcadepy import Arcade

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

````
</Tabs.Tab>
<Tabs.Tab>
```js
import Arcade from "@arcadeai/arcadejs";

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

</Tabs.Tab>
</Tabs>

### Authorize a tool directly

Many tools require authorization. For example, the `Gmail.ListEmails` 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.

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python
# 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:
USER_ID = "{arcade_user_id}"

# Request access to the user's Gmail account
auth_response = client.tools.authorize(
  tool_name="Gmail.ListEmails",
  user_id=USER_ID,
)

if auth_response.status != "completed":
    print(f"Click this link to authorize: {auth_response.url}")
```

</Tabs.Tab>
<Tabs.Tab>
```js
// 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:
const userId = "{arcade_user_id}";

// Request access to the user's Gmail account
const authResponse = await client.tools.authorize({
tool_name: "Gmail.ListEmails",
user_id: userId,
});

if (authResponse.status !== "completed") {
console.log(`Click this link to authorize: ${authResponse.url}`);
}

````

</Tabs.Tab>
</Tabs>

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

### Check for authorization status

You can wait for the authorization to complete using the following methods:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
  <Tabs.Tab>
    ```python
    client.auth.wait_for_completion(auth_response)
    ```
  </Tabs.Tab>
  <Tabs.Tab>

    ```js
    await client.auth.waitForCompletion(authResponse);
    ```
  </Tabs.Tab>
</Tabs>


### 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`:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>


```python
emails_response = client.tools.execute(
    tool_name="Gmail.ListEmails",
    user_id=USER_ID,
)
print(emails_response)
````

</Tabs.Tab>
<Tabs.Tab>

```js
const emailsResponse = await client.tools.execute({
  tool_name: "Gmail.ListEmails",
  user_id: userId,
});

console.log(emailsResponse.output.value);
```

</Tabs.Tab>
</Tabs>

Arcade remembers the user's authorization tokens, so you don't have to! Next time the user runs the same tool, they won't have to go through the authorization process again until the auth expires or is revoked.

### How it works

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

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.

</Steps>

### Next steps

Arcade also allows you to [build your own tools](/guides/create-tools/tool-basics/build-mcp-server) to integrate any custom functionality or API to your Agent or AI workflows.

Your tools can use the [service providers supported by Arcade](/references/auth-providers) or you can integrate with any [OAuth2-compatible service](/references/auth-providers/oauth2).