upskill-event-manager/wordpress-dev/ZOHO-OAUTH-SETUP.md

Zoho OAuth Setup Instructions

Prerequisites

• Zoho CRM account
• Admin access to create OAuth applications
• Access to staging server terminal

Step 1: Create Zoho OAuth Application

1. Go to Zoho API Console

2. Click "Add Client" or "Create New Client"

3. Choose "Web Based" application type

4. Fill in the details:

   • Client Name: HVAC Community Events
   • Homepage URL: https://upskillhvac.com
   • Authorized Redirect URIs: http://localhost:8080/callback
   • Description: WordPress integration for HVAC event management

5. Click "Create" and save the credentials:

   • Client ID
   • Client Secret

Step 2: Configure Environment Variables

Add to your .env file:

ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here

Step 3: Run OAuth Setup

From your terminal:

cd /Users/ben/dev/upskill-event-manager/wordpress-dev
./bin/zoho-setup-complete.sh

This script will:

1. Start a local callback server
2. Generate the authorization URL
3. Open your browser for Zoho login
4. Handle the OAuth callback
5. Save the tokens

Step 4: Complete Authorization

1. When the browser opens, log in to Zoho
2. Review the permissions requested:
   • CRM Settings access
   • CRM Modules access
   • CRM Users access
   • CRM Organization access
3. Click "Accept" or "Allow"
4. You'll be redirected to localhost:8080/callback
5. Copy the authorization code from the page
6. Return to terminal and paste the code

Step 5: Verify Setup

The script will:

• Exchange the code for tokens
• Test the connection
• Save configuration to zoho-config.php
• Display success message

Manual Setup (Alternative)

If the automated script doesn't work:

1. Start callback server:

cd wordpress/wp-content/plugins/hvac-community-events/includes/zoho
php -S localhost:8080 callback-server.php

2. Generate authorization URL:

php test-integration.php

3. Open the URL in your browser
4. Complete authorization
5. Copy the code and paste when prompted

Testing the Integration

After setup, test on staging:

1. Go to WordPress Admin
2. Navigate to HVAC Community Events → Zoho CRM Sync
3. Click "Test Connection"
4. In staging mode, you'll see simulation results only

Troubleshooting

Common Issues

1. "Client authentication failed"

   • Double-check Client ID and Secret
   • Ensure no extra spaces in .env file

2. "Invalid redirect URI"

   • Make sure redirect URI in Zoho matches exactly: http://localhost:8080/callback
   • No trailing slash

3. Connection refused on localhost:8080

   • Ensure no other service is using port 8080
   • Try a different port if needed

4. Token expired

   • Tokens auto-refresh, but if issues persist, re-run setup

Debug Mode

Enable debug logging:

define('ZOHO_DEBUG_MODE', true);
define('ZOHO_LOG_FILE', '/path/to/debug.log');

Security Notes

• Never commit .env or zoho-config.php to version control
• Tokens are stored encrypted in WordPress options
• Refresh tokens are used for long-term access
• Staging mode prevents accidental production syncs

Support

For issues:

1. Check debug logs
2. Verify OAuth application settings
3. Review Zoho API documentation
4. Contact development team