Use a GoHighLevel Private Integration Token when you're automating accounts you control, and build a Marketplace app with OAuth when other agencies will install what you're making. That one sentence answers it for most people. The rest of this article is the detail behind it: how each option authenticates, what it costs you in effort, and the specific situations where the "obvious" choice is wrong. Get this decision right early and you avoid the most expensive mistake in HighLevel development, which is rebuilding your auth layer after you picked the wrong door.
The two options in plain terms
A Private Integration Token (PIT) is a single bearer token you generate inside an account's settings. You choose its scopes, copy it once, and use it to call API v2 for that account. There's no install flow and no user consent screen, because you already own the account. PITs replaced the old v1 API keys as the recommended way to do internal automation.
A Marketplace app is a distributable product. Any HighLevel account can install it, and installation runs through OAuth 2.0, so each install grants your app scoped, revocable access to that specific account. This is the only way to reach accounts you don't own, and it's how you build something thousands of agencies can use. The full build is covered in How to Build a GoHighLevel Marketplace App with OAuth 2.0.
Side by side
| Factor | Private Integration Token | Marketplace App (OAuth) |
|---|---|---|
| Who can it access? | Only accounts you own | Any account that installs it |
| Auth model | One static bearer token | OAuth 2.0 with rotating tokens |
| Setup effort | Minutes, in the UI | Days: install flow, storage, refresh |
| Token lifecycle | No expiry; rotate every ~90 days | Access ~24h, refresh rotates each use |
| User consent screen | None | Yes, per install |
| Distribution | Not distributable | Listed in the marketplace |
| Custom in-app UI | No | Yes, via Custom Pages |
| Workflow triggers/actions | No | Yes |
| Best for | Internal tools, client work you run | Products other agencies install |
When a Private Integration Token is the right call
Reach for a PIT whenever the accounts are yours. If you run an agency and want to sync your own sub-accounts to a database, push leads into HighLevel from a landing page you built, or run a nightly reconciliation job, a token is all you need. You create it, scope it, and start calling the API the same afternoon. No OAuth server, no callback route, no token-refresh logic to get wrong.
It's also the right choice for client work where you manage the account. If a client hands you their HighLevel and asks for a custom automation, generate a PIT inside their sub-account, store it securely on your side, and build. You get the same API v2 surface a Marketplace app has, without any of the distribution machinery.
The one discipline PITs require is rotation. Because the token doesn't expire on its own, it's a long-lived secret. HighLevel recommends rotating every 90 days, and the settings include rotate-and-expire controls to do it without downtime. Put a calendar reminder on it.
When you need a Marketplace app instead
The moment your software has to touch an account you don't own, PITs are off the table and you need OAuth. You can't ask a thousand agencies to paste a token into your product, and you wouldn't want the liability if they did. OAuth gives each customer a consent screen, scoped access, and a revoke button, which is exactly what installing third-party software should feel like.
There's also a capability gap that surprises people. Only Marketplace apps can render Custom Pages inside HighLevel and register workflow triggers and actions. If your idea includes an onboarding screen your users see in the CRM, or a trigger they drop into their own automations, you're building a Marketplace app regardless of how the auth shakes out. And with HighLevel waiving developer commission through the end of 2026, the marketplace is unusually attractive to ship into right now.
The trap: picking PIT because OAuth looks hard
Here's the mistake I see most. Someone wants to build a product other agencies will use, but OAuth feels like a lot of work, so they ship with Private Integration Tokens and a "paste your token here" box. It works in the demo. Then it falls apart: onboarding is clunky, you're storing customers' long-lived tokens with no consent trail, you can't offer Custom Pages or workflow triggers, and you have no clean way to handle a customer leaving. Migrating that to OAuth later means rebuilding auth while live customers depend on it.
If the honest answer to "will people I don't own install this?" is yes, build OAuth from day one. It's a few more days now against a painful rebuild later. That trade is not close.
A quick decision checklist
- Only automating accounts you own or manage? Use a Private Integration Token.
- Other agencies will install it? Build a Marketplace app.
- Need Custom Pages or workflow triggers/actions? Marketplace app, no exceptions.
- Just testing the API to learn it? Start with a PIT, it's the fastest path to a first successful call.
- Not sure if it'll ever be distributed? Assume it will and build OAuth if that's even plausible.
Whichever door you pick, the API v2 surface beyond auth is identical: same base URL, same Version header, same rate limits. The choice here is only about how you get the token, not what you can do once you have it. For the bigger picture on both paths, see the GoHighLevel custom development guide.
Frequently asked questions
Are Private Integration Tokens the same as the old API keys?
No. PITs replaced v1 API keys as the recommended approach for internal access. They're scoped, manageable, and work with API v2, which the old keys don't fully cover.
Can I start with a PIT and move to OAuth later?
You can, but if you already know the product will be distributed, don't. Migrating auth after launch means changing how every customer connects while they're relying on the app. Build OAuth up front when distribution is the goal.
Do both options use the same API endpoints?
Yes. Once you have a valid bearer token, the API v2 endpoints, the base URL, and the required Version header are identical. Only the way you obtain the token differs.
How often should I rotate a Private Integration Token?
Roughly every 90 days. Since the token doesn't expire on its own, rotation is what limits the damage if it ever leaks. The settings include controls to rotate without breaking your running integration.
