​
Connecting OAuth in GoHighLevel and Troubleshooting Complex Scenarios

​
Background and Purpose

This SOP provides a step-by-step guide to connect OAuth in GoHighLevel at both the agency and sub-account levels, including solutions for common troubleshooting issues. This applies to agencies using the 297/497 GoHighLevel plans, managing multiple sub-accounts, or operating AI automation agencies.

​
Benefits of Proper OAuth Configuration

  • ✅ Seamless CRM integration with buildassistants.app
  • ✅ Automated data synchronization across all sub-accounts
  • ✅ Centralized management of multiple client accounts
  • ✅ Reduced manual setup for new sub-accounts
  • ✅ Reliable AI assistant functionality across all connected accounts
  • ✅ Consistent user experience for all clients

​
Required Resources

​
Prerequisites

  • GoHighLevel Login Credentials (Agency & Sub-Accounts)
  • Incognito Browser or Standard Browser
  • Access to Agency Settings and Sub-Account Marketplace
  • Stable Internet Connection
  • buildassistants.app account with OAuth capabilities

​
Account Requirements

  • GoHighLevel 297/497 plan or higher
  • Agency-level access for centralized management
  • Sub-account permissions for direct connections
  • Admin rights for OAuth configuration

​
OAuth Connection Methods

​
Method Overview

There are two primary approaches to OAuth connection:
  1. Agency-Level Integration - Connects all sub-accounts under agency control
  2. Direct Connection - Individual sub-account connections for external or stubborn accounts

​
1. Agency-Level OAuth Integration

​
Purpose

Connect all sub-accounts within your agency through a centralized OAuth integration.

​
Step-by-Step Process

​
Access Agency Settings

  1. Navigate to Agency-Level Settings
    • Go to Home or Settings > Integrations
    • Ensure you’re logged into the main agency account

​
Initiate OAuth Connection

  1. Click on the relevant OAuth option for buildassistants.app
  2. Log in when prompted (ensure credentials are correct)
  3. Grant all required permissions during the OAuth flow

​
Confirm Successful Connection

  1. Look for visual confirmation:
    • Green link icon appears next to connected sub-accounts
    • Connection status shows as “Active”
    • OAuth scope includes all necessary permissions

​
Troubleshooting Agency-Level Issues

Connection Not Appearing:
  1. Use incognito browser to eliminate cache issues
  2. Access platform directly through app.gohighlevel.com (not white-labeled domain)
  3. Clear browser cache and cookies
  4. Try different browser if issues persist
Partial Connection:
  1. Verify agency permissions are sufficient
  2. Check sub-account ownership within agency
  3. Review OAuth scope for completeness

​
2. Sub-Account OAuth Integration

​
Purpose

Connect individual sub-accounts that belong to your agency but may not sync automatically.

​
Identification Process

​
Check Sub-Account Status

  1. Log into the sub-account under the agency
  2. Look for indicators:
    • Red banner stating “No Active CRM Connection”
    • Missing integration in settings
    • Error messages about connectivity

​
Agency-Level Connection Method

  1. Go to agency workspace in buildassistants.app
  2. Click “Connect Accounts”
  3. Select target sub-account from the list
  4. Wait for automatic synchronization

​
Success Indicators

  • Red banner disappears from sub-account
  • Green link icon appears in agency dashboard
  • Integration status shows as “Connected”

​
Handling Stubborn Accounts

​
When Agency-Level Fails

Some sub-accounts may resist automatic connection. In these cases:
  1. Log in directly to the problematic sub-account
  2. Navigate to Settings > Integrations
  3. Select “Connect to GHL (Direct Connection)”
  4. Complete OAuth flow for that specific account

​
Verification Steps

  • Check connection status in both agency and sub-account views
  • Test functionality with a simple API call
  • Verify data synchronization is working correctly

​
3. Connecting Sub-Accounts Outside the Agency

​
Purpose

Connect sub-accounts that are not owned by your agency but require integration with buildassistants.app.

​
When This Applies

  • Client accounts from other agencies
  • Transferred accounts with ownership changes
  • External partnerships requiring integration
  • Multi-agency collaboration scenarios

​
Direct Connection Process

​
Access External Account

  1. Go to app.gohighlevel.com
  2. Log into the external sub-account using provided credentials
  3. Verify account access and permissions

​
Initiate Direct Connection

  1. Navigate to Settings > Integrations
  2. Click “Connect GHL (Direct Connection)”
  3. Important: Do NOT use agency-level integration for external accounts

​
OAuth Configuration

  1. Select the specific sub-account from OAuth popup
  2. Ensure correct account is highlighted
  3. Grant all required permissions
  4. Complete OAuth authorization flow

​
Confirmation

  1. Verify green link icon appears
  2. Test connection with buildassistants.app
  3. Confirm data access is working properly

​
4. Troubleshooting Complex OAuth Issues

​
Common Problem Scenarios

​
Accounts Refusing Connection

Symptoms:
  • OAuth flow fails repeatedly
  • Connection appears successful but doesn’t work
  • Intermittent connectivity issues
Solutions:
  1. Verify account ownership:
    • Check if sub-account belongs to your agency
    • Confirm permissions are adequate
    • Review account transfer history
  2. Switch to Direct Connection:
    • Use individual account login
    • Bypass agency-level integration
    • Complete OAuth flow directly
  3. Check account status:
    • Ensure account is active
    • Verify subscription status
    • Confirm no billing issues

​
Sub-Accounts Outside Agency Scope

Symptoms:
  • Account doesn’t appear in agency dashboard
  • “Account not found” errors
  • Permission denied messages
Solutions:
  1. Use Direct Connection method (Step 3 above)
  2. Verify external account credentials
  3. Confirm account owner permissions
  4. Check for account restrictions

​
”You Don’t Own This Account” Error

Common Causes:
  • Transferred accounts with incomplete ownership changes
  • Shared accounts with multiple agency access
  • Archived accounts that were reactivated
Solutions:
  1. Use Direct Connection instead of agency integration
  2. Verify current account ownership with GoHighLevel support
  3. Request proper account transfer if needed
  4. Check account permissions and roles

​
OAuth Token Issues

Symptoms:
  • Connection works initially but fails later
  • Intermittent authentication errors
  • “Token expired” messages
Solutions:
  1. Refresh OAuth tokens:
    • Go to Agency-Level Settings
    • Find “Reset Connection” option
    • Re-authorize OAuth connection
  2. Clear cached tokens:
    • Log out of all GoHighLevel accounts
    • Clear browser cache
    • Re-establish connections
  3. Update OAuth scope:
    • Ensure all required permissions are granted
    • Check for new permission requirements
    • Re-authorize with updated scope

​
Advanced Troubleshooting

​
Multiple Browser Testing

  • Test with different browsers (Chrome, Firefox, Safari)
  • Use incognito/private mode to eliminate cache issues
  • Disable browser extensions that might interfere
  • Check for popup blockers preventing OAuth flow

​
Network and Connectivity

  • Test with different internet connections
  • Check firewall settings that might block OAuth
  • Verify DNS resolution for GoHighLevel domains
  • Test API connectivity independently

​
Account Verification

  • Confirm account is in good standing
  • Check subscription status and billing
  • Verify no security restrictions on account
  • Review recent account changes or transfers

​
Visual Connection Indicators

​
Success Indicators

  • ✅ Green link icon next to sub-account name
  • ✅ “Connected” status in integration settings
  • ✅ Removal of red warning banners
  • ✅ Successful API test calls

​
Failure Indicators

  • ❌ Red banner stating “No Active CRM Connection”
  • ❌ Missing green link icon
  • ❌ Error messages in integration settings
  • ❌ Failed API authentication

​
Definition of Done

The OAuth configuration process is complete when:
  • ✅ All relevant sub-accounts (agency and external) display a green link icon
  • ✅ “No Active CRM Connection” banner is removed from all accounts
  • ✅ Accounts are successfully connected via Agency or Direct OAuth Integration
  • ✅ API connectivity is verified and functional
  • ✅ Data synchronization is working correctly
  • ✅ buildassistants.app functionality is fully operational across all connected accounts

​
Testing and Validation

​
Connection Testing

  1. API Test Calls:
    • Test basic account information retrieval
    • Verify calendar access functionality
    • Confirm contact management capabilities
  2. Functionality Testing:
    • Test AI assistant integration
    • Verify workflow automation
    • Confirm real-time data synchronization
  3. Error Handling:
    • Test with invalid requests
    • Verify proper error messages
    • Confirm graceful failure handling

​
Maintenance and Monitoring

​
Regular Maintenance

  • Monthly OAuth token health checks
  • Quarterly connection verification
  • Monitor for authentication errors
  • Update OAuth scope as needed

​
Monitoring Best Practices

  • Set up alerts for connection failures
  • Track API success rates
  • Monitor authentication logs
  • Document connection issues and resolutions

​
FAQ

​
What should I do if my OAuth fails repeatedly?

A: Use the Direct Connection method and verify account ownership. If issues persist, try using an incognito browser and accessing through app.gohighlevel.com directly.

​
Can I connect a sub-account that is not owned by my agency?

A: Yes, use Direct Connection by logging into the external sub-account directly and completing the OAuth flow. Do not attempt agency-level integration for external accounts.

​
What if I see “You Don’t Own This Account”?

A: This typically occurs with transferred accounts or shared access scenarios. Use the Direct Connection process and verify account ownership with GoHighLevel support if needed.

​
How do I confirm a successful connection?

A: Look for the green link icon next to the sub-account, removal of red warning banners, and successful API test calls in buildassistants.app.

​
How often do I need to refresh OAuth tokens?

A: OAuth tokens typically last 60-90 days, but connections should remain stable. Only refresh if experiencing authentication errors or connection failures.

​
Can I connect multiple agencies to one buildassistants.app account?

A: Yes, but each agency requires separate OAuth configuration. Use Direct Connection for external agencies and Agency-Level Integration for your primary agency.

​
Best Practices

​
Security Considerations

  • Use strong, unique passwords for all GoHighLevel accounts
  • Enable two-factor authentication where available
  • Regularly review OAuth permissions and scope
  • Monitor access logs for unauthorized activity

​
Organizational Tips

  • Document all connected accounts and their connection method
  • Maintain a connection troubleshooting log
  • Train team members on proper connection procedures
  • Establish regular maintenance schedules

​
Performance Optimization

  • Connect accounts during low-usage periods
  • Test connections thoroughly before going live
  • Monitor API rate limits and usage
  • Implement proper error handling in integrations
This comprehensive OAuth configuration guide ensures reliable, secure connections between GoHighLevel and buildassistants.app across all account types and scenarios.