Toda integración con GoHighLevel empieza eligiendo una llave, y hay tres en el llavero: el Private Integration Token (PIT), el flujo OAuth de las apps de marketplace, y una tercera de la que casi nadie escribe con honestidad: la API interna que usa la propia aplicación web, no documentada y sin contrato. Elegir mal no se nota el primer día; se nota cuando el token expira en medio de la noche, cuando la app hay que instalarla en cincuenta subcuentas, o cuando un endpoint no oficial cambia sin aviso y se lleva tu integración por delante.
Este artículo mapea las tres llaves desde la experiencia de operar integraciones reales con las dos primeras (y de haber evaluado la tercera lo suficiente para explicar por qué casi nunca debe usarse): qué es cada una, cuándo corresponde, qué mantenimiento exige y qué riesgos carga. Es la decisión de autenticación completa, sin la parte que la documentación omite.
Respuesta rápida
- PIT (Private Integration Token): token por subcuenta con permisos delimitados (scopes), sin expiración automática. La vía correcta para integraciones propias: tu sistema, tus cuentas, tu control.
- OAuth: el flujo completo de las apps de marketplace: instalación por subcuenta, tokens que expiran y se refrescan, publicación opcional. La vía correcta cuando terceros instalarán tu integración.
- API interna (no oficial): los endpoints que usa la propia interfaz web. Más capacidades que la API pública, cero contrato: cambia sin aviso y puede violar los términos de servicio. Para producción, la respuesta corta es no.
- La regla: ¿es para ti? PIT. ¿Es para distribuir? OAuth. ¿La API pública no lo cubre? Rediseña o espera el endpoint; no hipoteques producción a lo no documentado.
| PIT | OAuth | API interna | |
|---|---|---|---|
| Para quién | Integraciones propias | Apps para terceros | Nadie en producción |
| Expiración | No expira (rotación manual) | Tokens que expiran y se refrescan | Sesiones de la app web |
| Permisos | Scopes por token | Scopes por app + consentimiento | Todo lo que la interfaz puede |
| Mantenimiento | Mínimo | Gestión de refresh tokens | Romperse es cuestión de tiempo |
| Contrato | API pública documentada | API pública documentada | Ninguno |
La tabla decide rápido. Los matices de cada columna son los que evitan los errores caros.
¿PIT, OAuth o API interna en GoHighLevel: cuál usar?
Usa un Private Integration Token para integraciones propias: se crea por subcuenta con scopes delimitados y no expira solo. Usa OAuth cuando construyes una app que otros instalarán: gestiona tokens con refresco y consentimiento por subcuenta. La API interna no documentada queda fuera de producción: no tiene contrato y cambia sin aviso.
PIT: la llave de las integraciones propias
El Private Integration Token es la incorporación más sensata que ha hecho la plataforma en materia de API: un token generado desde la propia subcuenta, con la lista exacta de permisos que le concedes, que funciona hasta que tú lo rotes. Sin flujo de autorización, sin refresh tokens, sin infraestructura de OAuth: creas la llave, la guardas como el secreto que es, y tu integración queda operativa en minutos. Es la llave con la que corren nuestros sistemas de reconciliación, respaldos y MCP en producción.
Las tres disciplinas que separan el uso profesional del descuidado: scopes mínimos (el token de un dashboard de lectura no necesita permisos de escritura; el «todo habilitado por si acaso» es la vulnerabilidad clásica), rotación programada (que no expire no significa que no deba renovarse: calendariza el cambio como cualquier credencial), y un token por sistema (el mismo PIT compartido entre tres integraciones convierte cualquier incidente en un apagón triple y cualquier auditoría en una adivinanza). Su límite natural: el PIT es de UNA subcuenta. Diez subcuentas propias son diez tokens gestionados, lo cual sigue siendo trivial; quinientas subcuentas de terceros ya no, y ahí empieza el territorio de la segunda llave. Detalle de agencia que ahorra confusiones: el nivel agencia tiene sus propias credenciales para las operaciones de plataforma (crear subcuentas, snapshots), separadas de los PIT por subcuenta, y conviene no mezclarlas en el mismo sistema sin etiquetarlas.
OAuth: la llave de las apps distribuibles
Cuando tu integración la instalarán otros (clientes, otras agencias, el público del marketplace), el PIT deja de escalar: no vas a pedirle a cada cliente que genere y te envíe un token. El flujo OAuth resuelve exactamente eso: tu app declara sus scopes, cada subcuenta la instala con su consentimiento, y tu sistema recibe tokens de acceso que expiran y se renuevan con refresh tokens. El costo es la maquinaria: almacenar tokens por instalación, refrescarlos antes de que venzan, manejar la revocación y los reintentos cuando el refresco falla. Es infraestructura conocida y bien documentada, pero es infraestructura: para una integración interna, es complejidad comprada sin necesidad.
El criterio de frontera es de destino, no de tamaño: una integración enorme para tus propias cuentas sigue siendo territorio PIT; una utilidad pequeña que instalarán diez clientes ya es territorio OAuth. Y hay un caso híbrido honesto: empezar con PIT para validar la integración en cuentas propias y migrar a OAuth cuando llegue la distribución, sabiendo desde el día uno que esa migración está en el mapa. Lo que nunca escala es el anti-patrón intermedio: pedirle PITs a terceros por WhatsApp y guardarlos en una hoja de cálculo.
La API interna: la llave que no debes usar (y por qué existe la tentación)
La aplicación web de GoHighLevel habla con su backend por endpoints propios que no están en la documentación pública, y cualquiera con las herramientas de desarrollador del navegador puede verlos. La tentación es real porque la brecha es real: la interfaz puede cosas que la API pública no expone, y tarde o temprano tu proyecto choca con una de ellas. Ahí aparece la pregunta incómoda: «¿y si llamamos al endpoint que usa la propia app?».
La respuesta de producción es no, por tres razones en orden de gravedad. Sin contrato: esos endpoints cambian cuando la plataforma lo necesite, sin aviso, sin changelog, sin período de gracia; tu integración no se degrada, se rompe. Autenticación frágil: funcionan con las sesiones de la aplicación, no con credenciales de integración: mantenerlas vivas programáticamente es un castillo de naipes. Términos de servicio: automatizar contra la API privada puede violar las condiciones de la plataforma, y el riesgo ya no es técnico sino de cuenta. La respuesta correcta ante la brecha es aburrida y funciona: rediseñar el flujo con las piezas públicas (API más webhooks, o la construcción vía snapshots), y dejar que la brecha se cierre: la API pública lleva años ensanchándose en cada release.
Cuándo NO necesitas pensar en nada de esto
Si tu integración cabe en conectores existentes (n8n, Make, Zapier con sus nodos oficiales), la gestión de llaves ya la hicieron ellos: configuras la conexión y a trabajar. Esta decisión aparece cuando construyes contra la API directamente, que es exactamente el momento en que vale tomarla bien, porque la llave elegida define el mantenimiento de los próximos años.
Errores comunes
- El PIT todopoderoso compartido: un token con todos los scopes usado por tres sistemas distintos. Un incidente, tres apagones, cero trazabilidad.
- OAuth para uso propio: montar el flujo completo con refresh tokens para conectar tu propia subcuenta es pagar el peaje de la distribución sin distribuir.
- PITs de terceros en hojas de cálculo: el anti-patrón de escala: si necesitas tokens de clientes, la respuesta se llama OAuth, no disciplina de spreadsheet.
- Producción sobre endpoints no documentados: funciona en la demo, funciona un trimestre, y el día que cambia nadie te avisó porque nadie te debía aviso.
- Credenciales en el código: en cualquiera de las vías, el token pertenece a un gestor de secretos, no al repositorio ni al workflow visible del equipo.
Preguntas frecuentes
No expira automáticamente: funciona hasta que lo rotes o lo revoques desde la subcuenta. Esa comodidad es también la razón para rotarlo por calendario propio: una credencial eterna filtrada es un problema eterno.
Los mínimos que el caso necesita, empezando por solo lectura cuando el sistema no escribe. Añadir un scope después cuesta un minuto; descubrir qué hizo un token con permisos de más cuesta una auditoría.
No: puedes crear la app y distribuirla de forma privada a las subcuentas que la instalen. La publicación en el marketplace es el paso opcional para distribución abierta, con su proceso de revisión.
Pertenecen a la generación anterior de la API, en retirada: todo proyecto nuevo debería nacer sobre la v2 con PIT u OAuth. Si mantienes algo sobre v1, la migración es cuestión de tiempo, y mejor programada que forzada.
En un gestor de secretos (las variables de entorno cifradas de tu plataforma serverless cuentan), nunca en el código, en el repositorio ni en documentos compartidos. Y un token por sistema, para que rotar o revocar uno no apague a los demás.
Criterios verificados operando integraciones con PIT y OAuth sobre la API v2 en producción, a julio de 2026. Si estás definiendo la arquitectura de acceso de una integración seria, esa decisión es parte de lo que implemento.
La idea que ordena el llavero
Las tres llaves no son tres opciones: son dos herramientas y una trampa. El PIT es la llave de tu casa; OAuth es el sistema de llaves para casas ajenas; y la API interna es la ganzúa que abre más puertas justamente porque nadie prometió que seguirían abiertas. Las integraciones que envejecen bien se reconocen en esta decisión: llave proporcional al destino, permisos proporcionales al uso, y ninguna dependencia de lo que la plataforma no firmó. Todo lo demás es mantenimiento que te buscaste.
