Errores de autenticación de CDP: claves API, tokens y contexto del equipo
TL;DR
Diagnosticar la autenticación de CDP en la primera fase fallida: búsqueda de API de negocio, problema de credenciales o apretón de manos de WebSocket.
Enviar la clave de API de negocio de Nstdata como x-api-key para las solicitudes HTTP de sesión. Incluir x-team-id al seleccionar un equipo unido con una clave personal.
Verificar que la sesión original esté ready antes de solicitar una credencial de automatización temporal.
Construir el encabezado de WebSocket a partir de headerName devuelto y accessToken. Prefijar Bearer solo para Authorization.
Solicitar nuevas credenciales para la sesión original en ejecución después de la expiración.
Registrar fases y códigos de estado sanitizados. Mantener claves API, tokens de corta duración y URLs firmadas completas privadas.
¿Por qué falla la autenticación de CDP en un navegador remoto?
La autenticación de CDP falla cuando el cliente no puede autorizar su conexión con el navegador deseado. Errores similares pueden originarse antes en el flujo de trabajo, incluida la selección del espacio de trabajo incorrecto o el intento de acuñar una credencial para una sesión finalizada. Identificar la primera solicitud que falló antes de rotar credenciales o iniciar otro navegador. Nstdata Cloud Browser.
Un trabajador utiliza la API de negocio para inspeccionar una sesión y solicitar una credencial de automatización. El cliente del navegador usa esa credencial temporal para conectarse a Chromium. Esas llamadas tienen diferentes destinos, encabezados y condiciones de éxito. Un gateway de WebSocket puede ser accesible mientras rechaza la autorización. Un trabajador también puede conectarse y aterrizar en la pestaña incorrecta. Ese error posterior pertenece a la selección de página y validación de tarea. Consulte la .
Utilice la clave de negocio para las solicitudes HTTP de Cloud Browser, la credencial de automatización acuñada para CDP y el inicio de sesión de la aplicación en su página autorizada. Mantenga la selección del espacio de trabajo consistente a lo largo de las llamadas a la API de negocio.
Operación
Credencial o campo
Señal para continuar
Inspeccionar una sesión
x-api-key y contexto de equipo aplicable
El ID de sesión original se resuelve
Emitir credenciales de automatización
Misma clave de negocio y contexto de equipo
La credencial devuelta pertenece a esa sesión y tiene una expiración actual
Conectarse a Chromium
URL CDP devuelta y encabezado
El cliente recibe el contexto de navegador esperado
Acceder a la aplicación
Cuenta de prueba aprobada o sesión de app
La app confirma la identidad y estado de tarea previstos
Obtenga una clave personal en Configuración → Cuenta y una clave de miembro del equipo en Miembros. Una clave de miembro del equipo selecciona su equipo vinculado. Una clave personal puede usar x-team-id opcional para un equipo unido. Omitir el encabezado del equipo para un espacio de trabajo personal. Mantenga las credenciales en su almacén secreto aprobado y asocie cada trabajo con su espacio de trabajo. Configuración de credenciales de Cloud Browser.
Playwright utiliza chromium.connectOverCDP() para conectarse a Chromium a través de CDP. Un servidor de navegador Playwright habla el protocolo de Playwright y utiliza un método de conexión diferente. La API BrowserType describe ambos métodos. Puppeteer también soporta un endpoint y encabezados de conexión. Puppeteer ConnectOptions.
¿Cómo determina qué solicitud falló?
Ejecute primero una búsqueda de sesión, emita una nueva credencial para esa sesión lista e intente una conexión. Esto produce una fase de error útil mientras mantiene los tokens de acceso privados.
Paso 1. Identificar la sesión original
Utilice el ID de sesión del registro de trabajo o abra Cloud Browser → Session History y seleccione la ejecución conocida en su espacio de trabajo. Si solo tiene un ID de solicitud de creación, concilie el intento de creación original antes de iniciar otro navegador. Consulte gestión del ciclo de vida de la sesión.
Paso 2. Inspeccionar la API de sesión
Realice GET /api/v1/cloud-browser/sessions/{sessionId} con la clave de negocio sin procesar y la selección de equipo opcional. Inspeccione data.state. Un estado creating o stopping cambia la siguiente acción. Para una sesión detenida, determine por qué finalizó y si se necesita otra sesión para una nueva tarea.
Paso 3. Emitir y validar una credencial
Envíe POST /api/v1/cloud-browser/sessions/{sessionId}/automation-credentials. Verifique los campos de respuesta sessionId, cdpUrl, headerName, accessToken, y expiresAt. Construya el encabezado a partir de los campos devueltos. Persista el ID de sesión no secreto en el trabajo en lugar de leer repetidamente un antiguo token de una caché.
Paso 4. Ejecutar un apretón de manos limitado
Instala playwright-core@1.65.1 con npm y usa Node.js 22.12 o posterior. Guarda los dos módulos a continuación. Establece NSTDATA_API_KEY, NSTDATA_SESSION_ID, y opcionalmente NSTDATA_TEAM_ID en el entorno. Ejecuta node auth.mjs en el mismo directorio. La porción gestionada requiere tu clave y una sesión lista. Confirma el apretón de manos respaldado por la cuenta en tu propio espacio de trabajo.
Guarda cloud-api.mjs.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('Set NSTDATA_API_KEY');const headers ={'x-api-key': key };if(process.env.NSTDATA_TEAM_ID) headers['x-team-id']= process.env.NSTDATA_TEAM_ID;if(body) headers['content-type']='application/json';let response;try{ response =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('API transport failed; reconcile the original operation'),{retryable:true});}const retryable = response.status===429|| response.status>=500;let result;try{ result =await response.json();}catch{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
Una sonda exitosa imprime una bandera de conexión y un conteo de contextos. Empareja eso con una afirmación de página si estás diagnosticando una tarea. Cierra el cliente y permite que el propietario detenga el navegador gestionado. Si la investigación en sí posee la sesión, usa Stop Browser y confirma que la sesión ha terminado.
¿Qué te dice cada error de HTTP y WebSocket?
Un error de HTTP de la API de sesión concierne a la solicitud del servicio. Un error de WebSocket concierne al transporte del navegador. Un estado recibido de la aplicación objetivo después de la conexión concierne a la aplicación. Etiqueta cada error con el paso en el que ocurrió.
Primera observación fallida
Área a verificar
Próxima acción
La API informa 401, 403 o 470
Clave de negocio, ámbito o espacio de trabajo
Confirma tipo de clave, permisos y equipo
La API informa 409
Conflicto de operación o estado de sesión
Inspecciona la sesión existente y crea parámetros
La API informa 410
Expiración del recurso
Busca la sesión original antes de generar credenciales
WebSocket informa 401 o 403
Credencial de automatización o política de puerta de enlace
Verifica la construcción del encabezado, expiración y sesión prevista
WebSocket se agota el tiempo de apretón de manos
Ruta de red o disponibilidad de sesión
Confirma el estado de ejecución y acceso seguro al WebSocket desde el trabajador
El objetivo abre una página de inicio de sesión inesperada
Autenticación de aplicación o elección de página
Confirma el inicio de sesión aprobado y la pestaña esperada
Un proxy o equilibrador de carga en la ruta saliente del trabajador puede manejar WebSockets de manera diferente a HTTPS. Reproduce desde el trabajador que falló. Compara las marcas de tiempo para la emisión de credenciales, el intento de conexión y la desconexión. Si la credencial expiró antes de usarse, solicítala más cerca de la conexión. Si el reloj está desincronizado, corrige el reloj y vuelve a probar.
Los problemas de autenticación generalmente requieren una condición cambiada antes de que un nuevo intento pueda ayudar. Una solicitud repetida con la misma clave incorrecta solo agrega ruido. Espera a crear una sesión o solicita un token nuevo para la misma sesión lista cuando sea apropiado. Cumple con una respuesta explícita de límite de tasa siguiendo la guía del servicio y la semántica HTTP 429.
¿Cómo se ve un incidente de conexión desde el lado del trabajador?
Un incidente de conexión se vuelve más fácil de diagnosticar cuando el trabajador preserva resultados para cada fase. Imagina que un espacio de trabajo de demostración informa un navegador listo, luego el trabajador recibe un HTTP 403 durante la emisión de credenciales. El navegador nunca ha visto un intento de conexión CDP. Compara el espacio de trabajo reconocido en la búsqueda con el utilizado por la llamada de credenciales. Si una clave de miembro del equipo está vinculada al espacio de trabajo de la sesión, usa esa misma identidad para ambas solicitudes. Para una clave personal, confirma que ambas llamadas lleven la misma selección de equipo autorizada.
Ahora considera una sesión lista y una respuesta exitosa de credenciales seguida de un tiempo de espera de WebSocket. Verifica la ruta de red saliente del trabajador y la expiración del token. Si el punto final puede ser alcanzado por un segundo trabajador correctamente configurado en el mismo entorno, compara la configuración de proxy y biblioteca del primer trabajador. Evita publicar la URL como parte de esta comparación. Mantén un temporizador separado para esperar en la preparación de la sesión, la emisión del token y la conexión WebSocket para que el próximo incidente te diga exactamente dónde se gastó el tiempo.
¿Cómo encaja Nstdata Cloud Browser en un flujo de trabajo de conexión en producción?
Nstdata Cloud Browser proporciona infraestructura de navegador gestionada para automatización y agentes de IA, con conexión CDP segura y una API de sesión distinta. Los trabajadores pueden conectarse a su navegador deseado mientras un operador lo inspecciona en Vista en Vivo. El navegador puede usar el enrutamiento de red incorporado configurado al inicio. La aplicación debería mantener un mapeo duradero del trabajo comercial a la sesión gestionada. Ese mapeo da a los ingenieros un lugar para comenzar cuando fallan la autenticación o la tarea.
Búsqueda de sesión. Confirma el estado del espacio de trabajo y del navegador antes de volver a intentar la conexión.
Credenciales CDP temporales. Solicita un token de acceso para la sesión lista elegida y mantenlo limitado a la ruta de conexión.
Inspección en vivo. Verifica la página del navegador cuando el transporte tiene éxito pero el flujo de trabajo aún falla. Usa la guía de depuración de automatización del navegador para correlacionar la evidencia de la página con un error del trabajador.
¿Qué debe contener el registro del incidente de conexión?
Un registro de incidente de conexión debe contener los IDs del trabajo y la sesión, la referencia del espacio de trabajo, la fase fallida, el tiempo, el estado sanitizado y el resultado del apagado. Incluye una breve instrucción de reproducción y la versión del paquete del cliente. Preserva solo los detalles de error necesarios para diagnosticar el transporte o los permisos. Nunca pegues un punto final firmado completo en el ticket ni incluyas la respuesta de credenciales en un artefacto CI.
Q: ¿Puede la clave API comercial autorizar el WebSocket CDP directamente?
Utiliza la credencial de automatización de corta duración emitida para esa sesión. La clave comercial autentica las solicitudes HTTP del ciclo de vida.
Q: ¿Por qué el panel puede ver una sesión mientras el trabajador obtiene 403?
El panel y el trabajador pueden actuar con diferentes identidades y selecciones de espacio de trabajo. Confirma que la clave del trabajador tenga acceso al espacio de trabajo de la sesión.
Q: ¿Qué prueba una búsqueda de sesión exitosa?
Prueba que la solicitud de servicio pudo leer una sesión. La preparación del navegador, la autorización CDP y la finalización exitosa de una tarea en el sitio web tienen sus propias verificaciones.
Q: ¿Puedo reutilizar detalles de conexión después de una desconexión?
Inspecciona la sesión original. Si permanece lista, solicita detalles frescos y utiliza el nuevo punto de enlace y encabezado.
Q: ¿Desconectar Playwright detiene la sesión gestionada?
Finaliza la sesión a través del flujo de trabajo propietario y espera a que esté ended. Una desconexión del cliente deja la limpieza del ciclo de vida al propietario.
Cree casos de prueba que aíslen las preferencias de enrutamiento y navegador. Utilice señales del navegador y resultados visibles de la aplicación para explicar las diferencias de configuración regional en una sesión de Cloud Browser.
Marcus Chen
Nov. 19th 2026
Inicia navegadores en la nube bajo demanda
Gestiona huellas digitales y CAPTCHA
Automatiza flujos de trabajo e impulsa agentes de IA
Desde la extracción de datos web y las pruebas hasta la automatización con IA, ejecútalo todo en la nube.