Zoho OAuth Setup Guide

Status: In Progress (Feb 17, 2026)
Priority: CRITICAL - Blocks Tier 2 graduation
Current State: Expired CRM token, need client credentials + scope expansion

---

Current Situation

✅ We Have:

• Zoho CRM tokens file: /home/node/.openclaw/credentials/zoho-crm-tokens.json
• Valid refresh_token (permanent, doesn't expire)
• Current scopes: ZohoCRM.modules.READ, ZohoCRM.users.READ

❌ Missing:

• Client ID and Client Secret (needed to refresh token)
• Expanded scopes for Books, Desk, Cliq (needed for full automation)

🔴 Problem:

• Access token expired (last refreshed Feb 9, expires after 1 hour)
• All CRM API calls returning 401 INVALID_TOKEN

---

Step 1: Get Client Credentials (URGENT)

You need to retrieve from Zoho API Console:

1. Go to https://api-console.zoho.com/
2. Log in with your Zoho account (quan@ztag.com or main account)
3. Find your existing "Self Client" app (or create new one if needed)
4. Copy the following:
   • Client ID (long string starting with 1000.)
   • Client Secret (long alphanumeric string)

Where to store them:
Create file: /home/node/.openclaw/credentials/zoho-client-secret.json

{
  "client_id": "1000.XXXXXXXXXXXXXXXXXXXXXXXXXX",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "notes": "Zoho Self Client - created [DATE]"
}

⚠️ Security: This file is gitignored. Never commit to repo.

---

Step 2: Refresh Current Token (Test)

Once you provide client_id and client_secret:

cd /home/node/.openclaw/workspace
python3 tools/zoho-refresh-token.py

This will:

• Use refresh_token to get new access_token
• Update /credentials/zoho-crm-tokens.json
• Test CRM API access
• Report success/failure

---

Step 3: Expand Scopes (CRITICAL for Tier 2)

Current scopes (READ ONLY):

• ZohoCRM.modules.READ
• ZohoCRM.users.READ

Required scopes for full automation:

Zoho CRM (Carmee pathway automation)

• ZohoCRM.modules.ALL - Read/write contacts, deals, accounts, leads
• ZohoCRM.settings.ALL - Read pipelines, stages, custom fields
• ZohoCRM.users.READ - (already have)
• ZohoCRM.org.READ - Organization info

Zoho Books (Financial automation)

• ZohoBooks.fullaccess.all - Read/write invoices, expenses, payments
• Or more granular:
  • ZohoBooks.invoices.READ
  • ZohoBooks.invoices.CREATE
  • ZohoBooks.expenses.READ

Zoho Desk (Support automation)

• Desk.tickets.READ - Read support tickets
• Desk.tickets.UPDATE - Update ticket status, add responses
• Desk.contacts.READ - Customer info

Zoho Cliq (Team notifications)

• Cliq.Messages.CREATE - Send chat notifications
• Cliq.Channels.READ - Read channel list

---

Step 4: Generate New Authorization Code (Manual Process)

This requires browser access to Zoho API Console:

1. Go to https://api-console.zoho.com/
2. Navigate to your Self Client
3. Click "Generate Code" tab
4. Enter scopes (comma-separated):

   ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.users.READ,ZohoCRM.org.READ,ZohoBooks.fullaccess.all,Desk.tickets.READ,Desk.tickets.UPDATE,Desk.contacts.READ,Cliq.Messages.CREATE,Cliq.Channels.READ
   

5. Set expiry: 3 minutes (default)
6. Description: "Full automation scopes - Minnie COO Feb 2026"
7. Click CREATE
8. Copy the generated authorization code (long string)

⚠️ Time-sensitive: Authorization code expires in 3 minutes. Have terminal ready.

---

Step 5: Exchange Code for Tokens

Immediately after generating code:

cd /home/node/.openclaw/workspace
python3 tools/zoho-crm-oauth.py \
  <CLIENT_ID> \
  <CLIENT_SECRET> \
  <AUTHORIZATION_CODE>

This will:

• Exchange code for new tokens with expanded scopes
• Save to /credentials/zoho-crm-tokens.json
• Overwrite old tokens (backup created automatically)

---

Step 6: Implement Auto-Refresh (Like Gmail)

Once we have valid tokens with full scopes:

1. Update tools/zoho-refresh-token.py to load client credentials
2. Add cron job to refresh every 45 minutes
3. Test all services:
   • CRM: Read deals, create contact
   • Books: Read invoices
   • Desk: Read tickets
   • Cliq: Send test message

---

Testing Checklist

After token refresh:

• CRM API: python3 tools/zoho-crm-test.py
• Books API: (create test script)
• Desk API: (create test script)
• Cliq API: (create test script)

Expected results:

• ✅ All APIs return 200 OK
• ✅ Can read data from each service
• ✅ Scopes match authorization

---

Security Notes

Credential files (gitignored):

• /credentials/zoho-client-secret.json - Client ID/secret
• /credentials/zoho-crm-tokens.json - Access/refresh tokens

Backup location:

• Store copy in Quan's 1Password vault
• Label: "Zoho API Self Client - ZTAG Automation"

Rotation policy:

• Client credentials: Review quarterly
• Access tokens: Auto-refresh every 45 min
• Refresh tokens: Permanent (unless revoked)

---

Timeline

Immediate (Today):

1. Get client_id/secret from Zoho console → 5 min
2. Refresh current token → 2 min
3. Test CRM access → 1 min

Phase 2 (This week):

1. Generate new auth code with full scopes → 5 min
2. Exchange for new tokens → 2 min
3. Implement auto-refresh cron → 15 min
4. Test all services → 30 min

Total time: ~1 hour (mostly waiting for browser/API calls)

---

Troubleshooting

Error: "INVALID_TOKEN"

• Access token expired (happens after 1 hour)
• Solution: Refresh using refresh_token

Error: "INVALID_CLIENT"

• Client_id or client_secret wrong
• Solution: Re-check Zoho API Console

Error: "insufficient scope"

• Token doesn't have required permission
• Solution: Generate new auth code with correct scopes

Error: "code expired"

• Authorization code timeout (3 min)
• Solution: Generate new code, exchange immediately

---

Next Action: Retrieve client_id and client_secret from Zoho API Console.

Once you provide those, I can implement the full refresh + auto-refresh system in ~15 minutes.