How to retrieve services in Zoho

Retrieving Zoho services through the API layer requires a valid OAuth connection, a live access token, and the correct app type — get any one of these wrong and every downstream call will silently return None.

Why this matters

When you build automations or integrations on top of Zoho CRM or Zoho Desk, every tool call must first resolve a working API instance for the authenticated user. If the connection lookup fails, or the token has expired without being refreshed, no service data will be returned. Understanding the full retrieval chain — from database lookup through token refresh to API instantiation — lets you diagnose failures quickly and build more resilient integrations. As independent expert support for Zoho (not official Zoho support), Beam Help documents this flow so your team can maintain it confidently.

Step-by-step

Step 1. Confirm your environment variables are in place before attempting any connection. At minimum you need ZOHOCLIENTID, ZOHOCLIENTSECRET, and OPENROUTERAPIKEY defined in a .env file at the project root. You can also set ZOHO_DC to target a specific data centre (for example eu, in, com.au, or jp; the default is com). ^[8]

Step 2. Make sure the server is running before any retrieval attempt. Start it with:

python3 server.py

You can confirm it is listening by running lsof -i :8080. ^[8]

Step 3. Retrieve the stored Zoho connection for a given user by calling getzohoconnection(userid). This function queries the zohoconnections table for the matching user_id. If no row is found, the function returns None and no further retrieval is possible. ^[3]

Step 4. The connection function automatically handles token expiry. It compares the current time against tokenexpiresat, applying a 120-second early-refresh buffer to reduce mid-request 401 errors. When a refresh is needed, it calls ZohoOAuth.refreshtokens() with the stored refreshtoken, then writes the new accesstoken and updated tokenexpires_at back to the database before returning the refreshed connection object. ^[3]

Step 5. Pass the resolved connection into getzohoapi(userid, apptype), specifying either "crm" or "desk" as the apptype. This function calls getzoho_connection internally, so if the connection is missing it returns (None, None) immediately. ^[1]

Step 6. For Zoho Desk specifically, the function also requires an orgid. It reads deskorgid from the connection record. If that field is empty, it auto-discovers the organisation by calling api.getall_organizations(), then extracts the first item's id from the returned data list and persists it for future calls. ^[1]

Step 7. For Zoho CRM, you can verify the connection is working by checking that the stored crmorgid is present in the zohoconnections table. The test harness does this by fetching the most recent row and passing crmorg_id into a sandbox-org validation step. ^[5]

Step 8. Once you have a live API instance, tool calls are dispatched through executetoolwithrepair(), which accepts the api object, the apptype, a tool name string, and a params dictionary. The streaming layer emits a status event — "Calling Zoho tool: <toolname>..." — before each execution so you can observe progress in real time. ^[2]

Step 9. If you need to retrieve user or organisation details independently of a tool call, use ZohoOAuth.getuserinfo(accesstoken). This hits https://accounts.zoho.<DC>/oauth/user/info with a Bearer token header and returns fields including ZUID (user ID), Email, and organisation identifiers. Note that field names vary by data centre — the function tries orgid, organization_id, and ZGID in sequence before falling back to the user ID. ^[4]

Common pitfalls

• Missing orgid for Desk calls. If deskorg_id is not stored and the auto-discovery call also fails, the Desk API client will be initialised with an empty string, causing all subsequent Desk requests to fail silently. Always verify the org ID is persisted after the first successful connection. ^[1]
• Token refresh returning no accesstoken. The tokenrefresher closure checks for the key "accesstoken" in the refresh response; if it is absent, the refresher returns None and the API instance will use a stale token. This typically means the refreshtoken itself has expired and the user must reconnect via the OAuth flow. ^[1]
• Data-centre mismatch. The ZOHO_DC environment variable must match the region where the Zoho account was created. A mismatch causes OAuth and API calls to hit the wrong endpoint, producing authentication errors even with valid credentials. ^{[4] [8]}
• Browser tool authentication. If you are using browser-based tools (e.g. browsernavigateandscreenshot), the browser session is authenticated separately from the API session. An expired browser session returns an actionrequired error prompting a POST /api/browser/login call rather than a standard token refresh. ^[6]

What to check

• Confirm a row exists in zohoconnections for the target userid and that tokenexpiresat is a valid future Unix timestamp. ^[3]
• Verify that deskorgid (for Desk) or crmorgid (for CRM) is populated in the connection record so the API instance initialises with the correct organisation context. ^{[1] [5]}
• After any environment change, restart the server (pkill -f "python3 server.py"; sleep 1; python3 server.py) and re-run a connection check to ensure the new variables are loaded. ^[8]