Zoho CRM OAuth Setup Guide

Purpose: Enable Minnie to read deal data from Zoho CRM for Carmee's agentic assistant
Scopes Required: ZohoCRM.modules.deals.READ, ZohoCRM.modules.contacts.READ, ZohoCRM.modules.notes.READ
Date: February 17, 2026

---

Overview

Zoho CRM uses OAuth 2.0 for API access. This guide walks through:

1. Creating a Zoho API client (one-time setup)
2. Generating OAuth credentials
3. Authorizing access (manual browser flow)
4. Storing refresh token for automated renewal

---

Step 1: Create Zoho API Client

1.1 Access Zoho API Console

1. Go to: https://api-console.zoho.com/
2. Log in with your Zoho account (quan@ztag.com)

1.2 Create New Client

1. Click "Add Client" or "Get Started"
2. Select "Server-based Applications"

1.3 Configure Client Details

• Client Name: Minnie CRM Integration (or any descriptive name)
• Homepage URL: https://openclaw.ai (or ZTAG website)
• Authorized Redirect URIs:
  • Add: http://localhost:8080/oauth/callback
  • (This is where Zoho sends the auth code after approval)

1.4 Save Client

• Click "Create"
• You'll receive:
  • Client ID (long alphanumeric string)
  • Client Secret (long alphanumeric string)
• IMPORTANT: Copy both immediately and store securely

---

Step 2: Store Client Credentials

2.1 Create Credentials File

On the VPS, create: /home/node/.openclaw/credentials/zoho-crm-client-secret.json

{
  "client_id": "PASTE_CLIENT_ID_HERE",
  "client_secret": "PASTE_CLIENT_SECRET_HERE",
  "redirect_uri": "http://localhost:8080/oauth/callback",
  "auth_uri": "https://accounts.zoho.com/oauth/v2/auth",
  "token_uri": "https://accounts.zoho.com/oauth/v2/token"
}

File permissions:

chmod 600 /home/node/.openclaw/credentials/zoho-crm-client-secret.json

---

Step 3: Generate Authorization URL

3.1 Required Scopes

For Carmee's assistant, we need:

• ZohoCRM.modules.deals.READ - Pull deal pipeline data
• ZohoCRM.modules.contacts.READ - Customer history
• ZohoCRM.modules.notes.READ - Internal deal notes

3.2 Generate URL

Run this command on the VPS:

cd /home/node/.openclaw/workspace
python3 tools/zoho-crm-oauth-init.py

Expected output:

Zoho CRM OAuth Authorization URL:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.deals.READ,ZohoCRM.modules.contacts.READ,ZohoCRM.modules.notes.READ&client_id=YOUR_CLIENT_ID&response_type=code&access_type=offline&redirect_uri=http://localhost:8080/oauth/callback

Copy this URL and open it in your browser.

3.3 Notes

• access_type=offline ensures we get a refresh token (for automated renewal)
• Redirect URI must match exactly what you configured in Step 1.3

---

Step 4: Authorize Access (Manual Browser Flow)

4.1 Open Authorization URL

1. Copy the URL from Step 3.2
2. Paste into your browser (must be logged into quan@ztag.com Zoho account)

4.2 Grant Permissions

1. Zoho will show: "Minnie CRM Integration wants to access your Zoho CRM data"
2. Review requested scopes:
   • Read Deals
   • Read Contacts
   • Read Notes
3. Click "Accept"

4.3 Capture Authorization Code

1. Browser will redirect to: http://localhost:8080/oauth/callback?code=LONG_AUTH_CODE
2. Browser will show error (localhost not running - this is expected)
3. Copy the entire code=... value from the URL bar

Example URL:

http://localhost:8080/oauth/callback?code=1000.abcd1234efgh5678.ijkl9012mnop3456

Copy this part: 1000.abcd1234efgh5678.ijkl9012mnop3456

---

Step 5: Exchange Code for Tokens

5.1 Run Token Exchange Script

On the VPS:

cd /home/node/.openclaw/workspace
python3 tools/zoho-crm-oauth-exchange.py "PASTE_AUTH_CODE_HERE"

Replace PASTE_AUTH_CODE_HERE with the code from Step 4.3.

5.2 Expected Output

✓ Tokens retrieved successfully

Access Token: 1000.abcdef123456...
Refresh Token: 1000.ghijkl789012...
Expires In: 3600 seconds (1 hour)

✓ Tokens saved to: /home/node/.openclaw/credentials/zoho-crm-tokens.json

5.3 Verify Token File

cat /home/node/.openclaw/credentials/zoho-crm-tokens.json

Should contain:

{
  "access_token": "1000.abcdef...",
  "refresh_token": "1000.ghijkl...",
  "expires_in": 3600,
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "scope": "ZohoCRM.modules.deals.READ ZohoCRM.modules.contacts.READ ZohoCRM.modules.notes.READ"
}

---

Step 6: Test API Access

6.1 Test Deal Retrieval

cd /home/node/.openclaw/workspace
python3 tools/zoho-crm-test.py

Expected output:

Testing Zoho CRM API access...

✓ Access token valid
✓ Connected to: https://www.zohoapis.com

Fetching deals (limit 5)...

Deal #1: [Deal Name] - Stage: [Qualification/Proposal/etc.]
Deal #2: ...
Deal #3: ...

✓ Test successful! Zoho CRM API is working.

6.2 Troubleshooting

Error: "invalid_code"

• Auth code already used or expired (valid for ~60 seconds)
• Generate new authorization URL (Step 3) and repeat Step 4-5

Error: "invalid_client"

• Client ID or Secret incorrect
• Verify credentials file (Step 2)

Error: "insufficient_scope"

• Requested scopes not granted during authorization
• Re-authorize with correct scopes (Step 3-5)

Error: "INVALID_TOKEN" when testing

• Access token expired (1 hour validity)
• Refresh token should auto-renew, but if not, re-run token exchange

---

Step 7: Automated Token Refresh

7.1 Token Expiration

• Access tokens expire after 1 hour
• Refresh tokens remain valid indefinitely (until revoked)

7.2 Auto-Refresh Script

Script: tools/zoho-crm-refresh-token.py

Usage:

python3 tools/zoho-crm-refresh-token.py

Scheduled refresh: Add to cron (runs every 50 minutes):

crontab -e

Add line:

*/50 * * * * cd /home/node/.openclaw/workspace && python3 tools/zoho-crm-refresh-token.py >> /tmp/zoho-crm-token-refresh.log 2>&1

---

Step 8: Integration with Carmee Agent

8.1 API Usage in Agent

When Carmee agent needs deal data:

from tools.zoho_crm_client import ZohoCRMClient

# Initialize client (auto-loads tokens, auto-refreshes if needed)
crm = ZohoCRMClient()

# Fetch deal by ID
deal = crm.get_deal("1234567890")

# Returns:
{
  "Deal_Name": "Oakland School District - Grant Funded",
  "Stage": "Qualification",
  "Contact_Name": "Jane Smith",
  "Amount": 50000,
  "Closing_Date": "2026-03-15",
  "Description": "ELOP grant, 150 students, after-school program"
}

8.2 Context Enrichment

Agent uses deal data to:

1. Classify pathway (grant keywords → Pathway 1)
2. Understand decision stage (Qualification → early outreach tone)
3. Pull contact history (previous proposals, meeting notes)
4. Suggest next steps (timeline based on stage)

---

Security Notes

Credential Storage

• Client Secret: Stored in /home/node/.openclaw/credentials/zoho-crm-client-secret.json (600 permissions)
• Tokens: Stored in /home/node/.openclaw/credentials/zoho-crm-tokens.json (600 permissions)
• Never commit to Git (both files in .gitignore)

Token Security

• Access tokens are short-lived (1 hour)
• Refresh tokens are long-lived but can be revoked in Zoho console
• If compromised, revoke in: https://accounts.zoho.com/home#sessions/userconnectedapps

Scope Limitation

• Only requested read scopes (deals, contacts, notes)
• Cannot write/modify CRM data (preserves human-in-the-loop)
• Cannot delete records

---

Zoho Data Center

Zoho has multiple data centers. Ensure you're using the correct API domain:

• US: https://www.zohoapis.com (most common)
• EU: https://www.zohoapis.eu
• IN: https://www.zohoapis.in
• AU: https://www.zohoapis.com.au
• CN: https://www.zohoapis.com.cn

Check your account's data center:

1. Go to: https://accounts.zoho.com/home
2. Look for "Data Center" in account settings
3. Update api_domain in token file if needed

---

Maintenance

Token Refresh Monitoring

Check refresh logs:

tail -f /tmp/zoho-crm-token-refresh.log

API Rate Limits

Zoho CRM API limits (as of 2026):

• Standard edition: 5,000 API calls/day
• Professional/Enterprise: 25,000+ API calls/day

For Carmee agent: Estimated 50-100 API calls/day (well under limit)

Revoking Access

If needed, revoke API access:

1. Go to: https://accounts.zoho.com/home#sessions/userconnectedapps
2. Find "Minnie CRM Integration"
3. Click "Revoke"

---

Support

Zoho API Documentation: https://www.zoho.com/crm/developer/docs/api/v3/
Zoho Developer Forum: https://help.zoho.com/portal/en/community/topic/zoho-crm
OpenClaw Zoho Integration Docs: (This file)

---

Changelog

• 2026-02-17: Initial setup guide created
• Future: Add bulk deal fetching, contact enrichment, notes parsing

---

Next Steps

After completing this setup:

1. ✅ Zoho CRM API access enabled
2. → Test shadow mode with 5-10 sample inquiries
3. → Validate pathway classification accuracy
4. → Compare draft quality vs. custom GPT
5. → If validated, integrate with Zoho Cliq

See: working/ops/carmee-agent-shadow-testing.md for testing protocol.