Zoho

The Zoho auth provider enables tools and agents to call Zoho APIs  on behalf of a user using OAuth 2.0 authentication.

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, which provides pre-built tools for interacting with Zoho Books
• The Arcade Zoho Creator API MCP Server, which provides pre-built tools for interacting with Zoho Creator
• Your app code that needs to call Zoho APIs
• Or, your custom tools that need to call Zoho APIs

Configuring Zoho auth

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:

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

• Zoho OAuth 2.0 Authentication 
• Zoho Books API Documentation 
• Zoho Creator API Documentation 

Next, add the Zoho app to Arcade.

Configuring your own Zoho Auth Provider in Arcade

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

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

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

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 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 to understand how this works.

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

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...

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...

Using Zoho auth in custom tools

You can use the pre-built Arcade Zoho MCP Servers (Zoho Books, Zoho Creator) 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 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:

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 
• Zoho Creator API Scopes 

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:

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