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

Use Arcade’s default Zoho auth provider

Arcade offers a default Zoho auth provider that you can use in the Arcade Cloud Platform. In this case, your users will see Arcade as the name of the application requesting permission. The default provider signs users in through the US data center (accounts.zoho.com).

If you choose to use Arcade’s Zoho auth, you don’t need to configure anything. Follow the Zoho Books API MCP Server examples to get started calling Zoho tools.

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: my-zoho-provider
      description: Zoho OAuth 2.0 provider
      enabled: true
      type: oauth2
      provider_id: zoho
      client_id: ${env:ZOHO_CLIENT_ID}
      client_secret: ${env:ZOHO_CLIENT_SECRET}

auth:
  providers:
    - id: my-zoho-provider
      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.eu/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.eu/oauth/v2/token"
          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.eu/oauth/v2/token"
          params:
            grant_type: refresh_token
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            refresh_token: "{{refresh_token}}"
          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="zoho",
    scopes=["ZohoBooks.invoices.READ"],
)
 
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
let authResponse = await client.auth.start(userId, "zoho", {
  scopes: ["ZohoBooks.invoices.READ"],
});
 
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.

Arcade does not have a dedicated Zoho auth class. Use the OAuth2() auth class to specify that a tool requires authorization with Zoho. The id must match the ID of the Zoho provider you created. To use Arcade’s default Zoho provider, set id="arcade-zoho". The context.authorization.token field will be automatically populated with the user’s Zoho token:

from typing import Annotated
 
import httpx
from arcade_mcp_server import Context, tool
from arcade_mcp_server.auth import OAuth2
 
 
@tool(
    requires_auth=OAuth2(
        id="my-zoho-provider",
        scopes=["ZohoBooks.invoices.READ"],
    )
)
async def get_zoho_invoices(
    context: Context,
    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.application.READ - Read access to application metadata
• ZohoCreator.meta.form.READ - Read access to form metadata
• ZohoCreator.form.CREATE - Add records through forms
• ZohoCreator.report.READ - Read access to 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.