> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildassistants.app/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Configuration

## 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.