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

# Zoho

The Zoho auth provider enables tools and agents to call [Zoho APIs](https://www.zoho.com/developer/) on behalf of a user using OAuth 2.0 authentication.

<Callout>
  Want to quickly get started with Zoho in your agent or AI app? Check out the
  pre-built Arcade Zoho MCP Servers: - [Zoho Books API MCP
  Server](/resources/integrations/payments/zoho-books-api) - [Zoho Creator API MCP
  Server](/resources/integrations/development/zoho-creator-api)
</Callout>

### What's documented here

This page describes how to use and configure Zoho auth with Arcade.

This auth provider is used by:

- The [Arcade Zoho Books API MCP Server](/resources/integrations/payments/zoho-books-api), which provides pre-built tools for interacting with Zoho Books
- The [Arcade Zoho Creator API MCP Server](/resources/integrations/development/zoho-creator-api), which provides pre-built tools for interacting with Zoho Creator
- Your [app code](#using-zoho-auth-in-app-code) that needs to call Zoho APIs
- Or, your [custom tools](#using-zoho-auth-in-custom-tools) that need to call Zoho APIs

## Configuring Zoho auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own Zoho app credentials. This way, your users will see your application's name requesting permission.

Before showing how to configure your Zoho app credentials, let's go through the steps to create a Zoho app.

### Create a Zoho app

To integrate with Zoho's APIs, you'll need to set up OAuth 2.0 authentication by creating a client in the Zoho API Console:

<Steps>

#### Access the Zoho API Console

Navigate to the [Zoho API Console](https://api-console.zoho.com/) and sign in with your existing Zoho credentials or create a new account.

#### Create a new client

1. Once logged in, click on "Add Client" or "Get Started"
2. Select "Server-based Applications" as the client type
3. Fill in the required details:
   - **Client Name**: Choose a descriptive name for your application
   - **Homepage URL**: Provide the URL of your application's website
   - **Authorized Redirect URIs**: Add the redirect URL generated by Arcade (see configuration section below)

#### Configure client settings

1. After creating your client, you'll receive a `Client ID` and `Client Secret`
2. Configure the required scopes for your application based on which Zoho services you'll be using:
   - For Zoho Books: `ZohoBooks.fullaccess.all` or specific scopes like `ZohoBooks.invoices.READ`
   - For Zoho Creator: `ZohoCreator.meta.READ`, `ZohoCreator.report.READ`, etc.
   - Add other scopes as needed for your use case

#### Note your data center

Zoho operates in multiple data centers. Make note of which data center your account uses, as this affects the API endpoints:

- **US**: `.com` (e.g., `https://accounts.zoho.com`)
- **EU**: `.eu` (e.g., `https://accounts.zoho.eu`)
- **India**: `.in` (e.g., `https://accounts.zoho.in`)
- **Australia**: `.com.au` (e.g., `https://accounts.zoho.com.au`)
- **China**: `.com.cn` (e.g., `https://accounts.zoho.com.cn`)

</Steps>

For detailed instructions, refer to Zoho's official documentation:

- [Zoho OAuth 2.0 Authentication](https://www.zoho.com/accounts/protocol/oauth.html)
- [Zoho Books API Documentation](https://www.zoho.com/books/api/v3/)
- [Zoho Creator API Documentation](https://www.zoho.com/creator/help/api/v2/)

Next, add the Zoho app to Arcade.

## Configuring your own Zoho Auth Provider in Arcade

<Tabs items={["Dashboard GUI", "Configuration File"]}>
<Tabs.Tab>

### Configure Zoho Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **OAuth 2.0** tab at the top.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "arcade-zoho").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Zoho client.
- Configure the OAuth 2.0 endpoints (adjust the domain based on your data center):
  - **Authorization URL**: `https://accounts.zoho.com/oauth/v2/auth` (or `.eu`, `.in`, `.com.au`, `.com.cn`)
  - **Token URL**: `https://accounts.zoho.com/oauth/v2/token` (or `.eu`, `.in`, `.com.au`, `.com.cn`)
- Note the **Redirect URL** generated by Arcade. This must be set as your Zoho client's authorized redirect URI.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

</Tabs.Tab>

<Tabs.Tab>

### Configure Zoho Auth Using Configuration File

<Callout type="info">
  This method is only available when you are [self-hosting the
  engine](/guides/deployment-hosting/on-prem
</Callout>

<Steps>

#### Set environment variables

Set the following environment variables:

```bash
export ZOHO_CLIENT_ID="<your client ID>"
export ZOHO_CLIENT_SECRET="<your client secret>"
```

Or, you can set these values in a `.env` file:

```bash
ZOHO_CLIENT_ID="<your client ID>"
ZOHO_CLIENT_SECRET="<your client secret>"
```

#### Edit the Engine configuration

Edit the `engine.yaml` file and add a new item to the `auth.providers` section.

For US data center:

```yaml
auth:
  providers:
    - id: arcade-zoho
      description: Zoho OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:ZOHO_CLIENT_ID}
      client_secret: ${env:ZOHO_CLIENT_SECRET}
      oauth2:
        scope_delimiter: ","
        authorize_request:
          endpoint: "https://accounts.zoho.com/oauth/v2/auth"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            scope: "{{scopes}}"
            state: "{{state}}"
            access_type: offline
            prompt: consent
        token_request:
          endpoint: "https://accounts.zoho.com/oauth/v2/token"
          auth_method: client_secret_post
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json
        refresh_request:
          endpoint: "https://accounts.zoho.com/oauth/v2/token"
          auth_method: client_secret_post
          params:
            grant_type: refresh_token
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
          response_content_type: application/json
```

<Callout type="warning">
  If your Zoho account is in a different data center (EU, India, Australia, or
  China), replace `accounts.zoho.com` with the appropriate domain: - EU:
  `accounts.zoho.eu` - India: `accounts.zoho.in` - Australia:
  `accounts.zoho.com.au` - China: `accounts.zoho.com.cn`
</Callout>

</Steps>

</Tabs.Tab>
</Tabs>

When you use tools that require Zoho auth using your Arcade account credentials, Arcade will automatically use this Zoho OAuth provider. If you have multiple Zoho providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

## Using Zoho auth in app code

Use the Zoho auth provider in your own agents and AI apps to get a user token for Zoho APIs. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for Zoho APIs:

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

```python {8-12}
from arcadepy import Arcade

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

user_id = "{arcade_user_id}"

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="arcade-zoho",
    scopes=["ZohoBooks.fullaccess.all"]
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token
# Do something interesting with the token...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade();

const userId = "{arcade_user_id}";

// Start the authorization process
const authResponse = await client.auth.start(userId, "arcade-zoho", [
  "ZohoBooks.fullaccess.all",
]);

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

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

const token = authResponse.context.token;
// Do something interesting with the token...
```

</Tabs.Tab>

</Tabs>

## Using Zoho auth in custom tools

You can use the pre-built Arcade Zoho MCP Servers ([Zoho Books](/resources/integrations/payments/zoho-books-api), [Zoho Creator](/resources/integrations/development/zoho-creator-api)) to quickly build agents and AI apps that interact with Zoho.

If the pre-built tools don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with Zoho APIs.

Use the `OAuth2()` auth class to specify that a tool requires authorization with Zoho. The `context.authorization.token` field will be automatically populated with the user's Zoho token:

```python {8-12,22}
from typing import Annotated

import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2


@tool(
    requires_auth=OAuth2(
        provider_id="arcade-zoho",
        scopes=["ZohoBooks.invoices.READ"]
    )
)
async def get_zoho_invoices(
    context: ToolContext,
    organization_id: Annotated[str, "The Zoho Books organization ID."],
) -> Annotated[dict, "The list of invoices."]:
    """
    Retrieve invoices from Zoho Books.
    """
    url = f"https://books.zoho.com/api/v3/invoices?organization_id={organization_id}"
    headers = {
        "Authorization": f"Zoho-oauthtoken {context.authorization.token}",
    }

    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return dict(response.json())
```

## Available Scopes

Zoho supports various OAuth scopes that determine the level of access your application has. Scopes vary by Zoho service:

### Zoho Books Scopes

- `ZohoBooks.fullaccess.all` - Full access to all Zoho Books data
- `ZohoBooks.invoices.READ` - Read access to invoices
- `ZohoBooks.invoices.CREATE` - Create invoices
- `ZohoBooks.invoices.UPDATE` - Update invoices
- `ZohoBooks.invoices.DELETE` - Delete invoices
- `ZohoBooks.contacts.READ` - Read access to contacts
- `ZohoBooks.contacts.CREATE` - Create contacts
- And many more...

### Zoho Creator Scopes

- `ZohoCreator.meta.READ` - Read access to application metadata
- `ZohoCreator.report.READ` - Read access to reports
- `ZohoCreator.report.CREATE` - Create records in reports
- `ZohoCreator.report.UPDATE` - Update records in reports
- `ZohoCreator.report.DELETE` - Delete records from reports
- And many more...

For a complete list of available scopes, refer to the official documentation:

- [Zoho Books API Scopes](https://www.zoho.com/books/api/v3/oauth/#scopes)
- [Zoho Creator API Scopes](https://www.zoho.com/creator/help/api/v2/oauth-scopes.html)

## Data Center Considerations

Zoho operates in multiple data centers around the world. When making API calls, you must use the correct domain for your account's data center:

| Data Center | Accounts Domain        | API Domain Example                         |
| ----------- | ---------------------- | ------------------------------------------ |
| US          | `accounts.zoho.com`    | `books.zoho.com`, `creator.zoho.com`       |
| EU          | `accounts.zoho.eu`     | `books.zoho.eu`, `creator.zoho.eu`         |
| India       | `accounts.zoho.in`     | `books.zoho.in`, `creator.zoho.in`         |
| Australia   | `accounts.zoho.com.au` | `books.zoho.com.au`, `creator.zoho.com.au` |
| China       | `accounts.zoho.com.cn` | `books.zoho.com.cn`, `creator.zoho.com.cn` |

Make sure to configure your OAuth provider and API calls to use the correct domain for your account's data center.