Private Integration Tokens

Every API call to GoHighLevel requires authentication. Private Integration Tokens (PITs) are the primary method for connecting external tools, MCP servers, and custom integrations to your GHL account. Understanding how tokens work at both the agency and sub-account level is the first step before using any tool in this table.

What Is a Private Integration Token?

A Private Integration Token is a long-lived API key that grants programmatic access to GoHighLevel data and actions. Unlike OAuth tokens that expire and require refresh flows, PITs remain active until you revoke them. Each token is scoped to specific permissions, so you control exactly what an integration can read, write, or delete.

PITs are generated inside the GHL platform under your integration settings. You create them, assign scopes, and use them in the Authorization header of every API request as a Bearer token.

Agency-Level Tokens

Agency-level tokens operate across your entire GHL agency account. When you generate a token at the agency level, it can access data across all sub-accounts (locations) under your agency.

When to use agency-level tokens:

• Building tools that manage multiple client accounts from a single dashboard
• Running reporting or analytics across all locations
• Automating sub-account provisioning and configuration
• Syncing data between locations

How to generate one:

1. Log in to your GHL agency account
2. Navigate to Settings > Integrations > Private Integrations
3. Click Create New Integration
4. Give it a descriptive name (e.g., “MCP Server” or “Reporting Dashboard”)
5. Select the scopes your integration needs (contacts, conversations, opportunities, calendars, etc.)
6. Click Save and copy the generated token immediately. You will not be able to view it again.

Agency tokens include a companyId claim that identifies your agency. When making API calls, you specify which location to operate on by passing the locationId parameter or header.

Security note: Agency tokens are powerful. They can access every sub-account. Treat them like a master key. Store them in environment variables or a secrets manager, never in source code or client-side applications.

Sub-Account (Location) Level Tokens

Sub-account tokens are scoped to a single location. They can only access data within that one business account. This is the more common and more secure choice for most integrations.

When to use sub-account tokens:

• Connecting an MCP server to one specific client account
• Building automations for a single business
• Giving a contractor or tool limited access to one location
• Any situation where the integration only needs to touch one account

How to generate one:

1. Log in to your GHL sub-account (or switch to the sub-account from your agency view)
2. Navigate to Settings > Integrations > Private Integrations
3. Click Create New Integration
4. Name the integration clearly (e.g., “CRM Sync Tool” or “MCP Contacts”)
5. Select only the scopes this integration actually needs. Follow the principle of least privilege.
6. Click Save and copy the token immediately

Sub-account tokens include a locationId claim. Every API call made with this token automatically targets the correct location without needing to specify it separately.

Scopes and Permissions

Each PIT is assigned one or more scopes that control access. Common scopes include:

• contacts — read and write contact records, tags, notes, tasks
• conversations — send messages, manage threads, access recordings
• opportunities — manage deals, pipeline stages, followers
• calendars — create calendars, book appointments, check availability
• locations — read and configure sub-account settings
• workflows — list and monitor automation workflows
• blogs — manage blog content and categories
• social-media-posting — create and schedule social posts
• payments — access orders, transactions, subscriptions
• invoices — manage invoices, estimates, and billing
• products — manage product catalog and inventory
• custom-objects — work with custom object schemas and records

Only enable the scopes your integration actually uses. You can always edit the integration later to add more scopes if needed.

Using Your Token in API Calls

Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_TOKEN_HERE

For MCP server configurations, the token is typically set as an environment variable that the server reads at startup. The exact variable name depends on your MCP server implementation, but GHL_API_TOKEN or GHL_PIT are common conventions.

Token Management Best Practices

Rotate tokens periodically. Even though PITs do not expire automatically, rotating them every 90 days limits the damage window if a token is compromised.

Use separate tokens for separate tools. If you have an MCP server and a reporting dashboard, create a separate PIT for each. This way you can revoke one without breaking the other.

Audit token usage. Review your active integrations regularly under Settings > Integrations. Delete any tokens for tools you no longer use.

Never share tokens across environments. Use different tokens for development, staging, and production. If a dev token leaks, your production data stays safe.

Common Questions

Can I have multiple PITs for the same sub-account? Yes. You can create as many integrations as you need, each with different scopes and names. This is the recommended pattern for isolating access per tool.

What happens if I delete a Private Integration? The token is immediately revoked. Any tool using that token will start receiving 401 Unauthorized errors on every request. There is no grace period.

Can I see what API calls a token has made? GHL does not currently provide a per-token audit log. You can monitor activity through your MCP server logs or by tracking API responses in your own system.

Do PITs work with webhooks? PITs authenticate outbound API calls you make to GHL. Webhooks are inbound notifications from GHL to your server. Webhooks use a separate verification mechanism, not your PIT.

Is there a rate limit? Yes. GHL enforces rate limits on API calls. The exact limits depend on your plan and the endpoint. If you hit a rate limit, the API returns a 429 status code. Build in retry logic with exponential backoff for production integrations.

Related MCP Tools

• Location CRUD — Manage the sub-accounts your tokens connect to
• Location Custom Fields — Configure the fields your integrations will read and write
• Timezone Handler — Set correct timezone context for your API calls