GoHighLevel Private Integration Token Guide: Setup and Scopes

If you want to connect a script, a reporting tool or a third-party app to one HighLevel account without building a full marketplace app, you use a Private Integration token. This GoHighLevel Private Integration token guide covers where to create one, which scopes to pick, how to use it in API calls, and how to rotate it without breaking anything.

What a Private Integration token is

HighLevel describes a Private Integration token as a static OAuth2 access token. In practice:

• It's tied to one sub-account (or to the agency, if created at the agency level).
• It only allows the scopes you tick when you create it.
• It doesn't refresh or expire daily the way marketplace OAuth tokens do. It changes only when you rotate it.
• It works with API v2.0, the current API. The old v1 API keys are end-of-life and unscoped.

Who can create one

According to HighLevel's developer docs, agency admins can create and manage Private Integrations by default. Agency owners can restrict this per admin in the agency's Settings, under Team, in that user's Roles & Permissions, with separate toggles for agency-level and sub-account-level integrations.

How to create a GoHighLevel Private Integration token

As of October 2026, for a single sub-account:

1. Open the sub-account and go to Settings.
2. Click Private Integrations. (If it's missing, HighLevel's docs say the feature may need to be enabled in Labs.)
3. Click to create a new integration and give it a clear name, like "Reporting script" or "RGS Tools."
4. Select only the scopes the integration needs.
5. Create and confirm.
6. Copy the token immediately. HighLevel won't show it again.

Store it in a password manager or your hosting provider's secret settings, not in a shared doc or a front-end script.

Picking scopes

Scopes come in .readonly and .write pairs per area, such as contacts.readonly, contacts.write, locations/customFields.readonly and users.write. Tick the fewest you can:

• A tool that only reads field definitions needs only read scopes.
• A tool that creates fields needs the matching .write scope.
• If you're unsure, start read-only and add more later. HighLevel lets you edit scopes without changing the token.

Using the token in API calls

Send the token as a Bearer token, with HighLevel's version header:

GET https://services.leadconnectorhq.com/locations/{locationId}
Authorization: Bearer <your token>
Version: 2021-07-28

You'll often need the sub-account's location ID. It appears in the browser address bar when you're inside the sub-account (the string after /location/), and in the sub-account's business settings.

A few practical notes:

• Keep tokens server-side. Anyone with the token has its scopes.
• Respect rate limits. HighLevel documents a burst limit of 100 requests per 10 seconds and a daily limit of 200,000 requests for API v2 apps, and every response carries rate limit headers you can read.
• One token per integration makes it easy to revoke one without touching the others.

Rotating and revoking

HighLevel recommends rotating tokens every 90 days and gives you two ways to do it:

1. Rotate and expire this token later. Both the old and new token work for 7 days. Deploy the new one, confirm everything works, and the old one stops on its own. You can cancel the rotation or expire the old token early during that window.
2. Rotate and expire this token now. Use this if a token leaked. The old one stops immediately, so have the new one ready to deploy.

When an integration is no longer used, delete it from the three-dot menu in Private Integrations.

Testing a new token

Before you hand a token to a script or a tool, check it works:

1. In Postman or a similar client, send GET /locations/{locationId} with the headers above.
2. A 200 response with the sub-account's name means the token and location ID are right.
3. A 401 usually means the token was mistyped or rotated.
4. A 403 or a scope error means the token doesn't include the scope that endpoint needs. Edit the integration's scopes and try again; the token itself stays the same.

Test one read call for each area your integration uses (contacts, custom fields, users) so scope gaps show up now rather than in production.

Common mistakes

• Ticking every scope. It's tempting when something fails, but it turns a small leak into a big one.
• Pasting the token into a browser-side script. Anyone can read it there.
• Losing track of which token belongs to which tool. Name integrations clearly.
• Forgetting the location ID. Most endpoints need it, and a token for one sub-account won't work for another.

Where the native way gets slow

One token for one sub-account is easy. An agency with 40 sub-accounts is a different story: 40 tokens to create, store, rotate and keep straight. That's the main reason marketplace apps exist, since one install can cover the whole agency.

How RGS Tools uses tokens

RGS Tools supports both routes. You can approve the RGS marketplace app once for your whole agency, or connect a single sub-account with a Private Integration token. When you make a token, the setup screen shows every scope the tools need, once, so you can tick them in one pass. Tokens are encrypted and only used server-side for the calls you ask for.

Read-only tools ask for read-only access. Field Finder, for example, only reads field definitions, custom values and object schemas, and never writes to your sub-account. Once connected, you can browse keys, or run a sub-account compare. For a first API project with your new token, try finding custom field keys.