CDP Authentication Errors: API Keys, Tokens, and Team Context
TL;DR
Diagnose CDP authentication at the first failing phase: business API lookup, credential issue, or WebSocket handshake.
Send the Nstdata business API key as x-api-key for session HTTP requests. Include x-team-id when selecting a joined team with a personal key.
Verify that the original session is ready before requesting a temporary automation credential.
Build the WebSocket header from the returned headerName and accessToken. Prefix Bearer only for Authorization.
Request fresh credentials for the original running session after expiry.
Log sanitized phases and status codes. Keep API keys, short-lived tokens, and complete signed URLs private.
Why does CDP authentication fail on a remote browser?
CDP authentication fails when the client cannot authorize its connection to the intended browser. Similar errors can originate earlier in the workflow, including selection of the wrong workspace or attempting to mint a credential for an ended session. Identify the first request that failed before rotating credentials or starting another browser. Nstdata Cloud Browser.
A worker uses the business API to inspect a session and request an automation credential. The browser client uses that temporary credential to connect to Chromium. Those calls have different destinations, headers, and success conditions. A WebSocket gateway may be reachable while rejecting authorization. A worker may also connect and land on the wrong tab. That later error belongs to page selection and task validation. See the Playwright CDP connection guide.
Use the business key for Cloud Browser HTTP requests, the minted automation credential for CDP, and the application's own sign-in inside its authorized page. Keep workspace selection consistent throughout the business API calls.
Operation
Credential or field
Signal to continue
Inspect a session
x-api-key and applicable team context
The original Session ID resolves
Issue automation credentials
Same business key and team context
Returned credential belongs to that session and has a current expiry
Connect to Chromium
Returned CDP URL and header
Client receives the expected browser context
Access the application
Approved test account or app session
App confirms the intended identity and task state
Get a personal key from Settings → Account and a team member key from Members. A team member key selects its bound team. A personal key can use optional x-team-id for a joined team. Omit the team header for a personal workspace. Hold credentials in your approved secret store and bind each job to its workspace. Cloud Browser credential configuration.
Playwright uses chromium.connectOverCDP() to attach to Chromium over CDP. A Playwright browser server speaks the Playwright protocol and uses a different connection method. The BrowserType API describes both methods. Puppeteer also supports an endpoint and connection headers. Puppeteer ConnectOptions.
How do you determine which request failed?
Run a session lookup first, issue a new credential for that ready session, and attempt one connection. This produces a useful error phase while keeping access tokens private.
Step 1. Identify the original session
Use the Session ID from the job record or open Cloud Browser → Session History and select the known run in its workspace. If you only have a creation request ID, reconcile the original create attempt before starting another browser. See session lifecycle management.
Step 2. Inspect the session API
Make GET /api/v1/cloud-browser/sessions/{sessionId} with the raw business key and optional team selection. Inspect data.state. A creating or stopping state changes the next action. For a stopped session, determine why it ended and whether another session is needed for a new task.
Step 3. Issue and validate a credential
Send POST /api/v1/cloud-browser/sessions/{sessionId}/automation-credentials. Verify the response fields sessionId, cdpUrl, headerName, accessToken, and expiresAt. Construct the header from the returned fields. Persist the non-secret Session ID in the job rather than repeatedly reading an old token from a cache.
Step 4. Run a bounded handshake
Install playwright-core@1.65.1 with npm and use Node.js 22.12 or later. Save the two modules below. Set NSTDATA_API_KEY, NSTDATA_SESSION_ID, and optionally NSTDATA_TEAM_ID in the environment. Run node auth.mjs in the same directory. The managed portion requires your key and a ready session. Confirm the account-backed handshake in your own workspace.
Save 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);}
A passing probe prints a connection flag and context count. Pair that with a page assertion if you're diagnosing a task. Close the client, and let the owner stop the managed browser. If the investigation itself owns the session, use Stop Browser and confirm that the session ended.
What do HTTP and WebSocket errors each tell you?
An HTTP error from the session API concerns the service request. A WebSocket error concerns browser transport. A status received from the target application after connection concerns the application. Label each error with the step where it occurred.
First failing observation
Area to check
Next action
API reports 401, 403, or 470
Business key, scope, or workspace
Confirm key type, permissions, and team
API reports 409
Operation or session state conflict
Inspect the existing session and create parameters
API reports 410
Resource expiry
Look up the original session before minting credentials
WebSocket reports 401 or 403
Automation credential or gateway policy
Check header construction, expiry, and intended session
WebSocket handshake times out
Network path or session availability
Confirm running state and secure WebSocket access from the worker
Target opens an unexpected sign-in page
Application authentication or page choice
Confirm the approved sign-in and expected tab
A proxy or load balancer on the worker's outbound path may handle WebSockets differently from HTTPS. Reproduce from the worker that failed. Compare the timestamps for credential issue, connection attempt, and disconnect. If the credential expired before use, request it closer to attachment. If the clock is skewed, correct the clock and retest.
Authentication problems usually require a changed condition before a retry can help. A repeated request with the same wrong key only adds noise. Wait for a creating session or request a fresh token for the same ready session when appropriate. Honor an explicit rate-limit response by following the service guidance and the HTTP 429 semantics.
What does a connection incident look like from the worker's side?
A connection incident becomes easier to diagnose when the worker preserves results for each phase. Imagine that a demo workspace reports a ready browser, then the worker receives an HTTP 403 during credential issuance. The browser has never seen a CDP connection attempt. Compare the workspace recognized at lookup with the one used by the credential call. If a team member key is bound to the session's workspace, use that same identity for both requests. For a personal key, confirm that both calls carry the same authorized team selection.
Now consider a ready session and a successful credential response followed by a WebSocket timeout. Check the worker's outbound network path and the token expiry. If the endpoint can be reached by a second correctly configured worker in the same environment, compare the first worker's proxy and library configuration. Avoid publishing the URL as part of this comparison. Keep a separate timer for waiting on session readiness, token issuance, and the WebSocket connection so the next incident tells you exactly where time was spent.
How does Nstdata Cloud Browser fit a production connection workflow?
Nstdata Cloud Browser provides managed browser infrastructure for automation and AI agents, with secure CDP attachment and a distinct session API. Workers can connect to their intended browser while an operator inspects it in Live View. The browser can use built-in network routing configured at launch. The application should keep a durable mapping from business job to managed session. That mapping gives engineers a place to start when either authentication or the task fails.
Session lookup. Confirm workspace and browser state before retrying connection.
Temporary CDP credentials. Request an access token for the chosen ready session and keep it scoped to the attach path.
Live inspection. Check the browser page when transport succeeds but the workflow still fails. Use the browser automation debugging guide to correlate page evidence with a worker error.
A connection incident record should contain the job and session IDs, workspace reference, failed phase, time, sanitized status, and shutdown outcome. Include a short reproduction instruction and the client's package version. Preserve only the error details needed to diagnose transport or permissions. Never paste a complete signed endpoint into the ticket or include the credential response in a CI artifact.
Q: Can the business API key authorize the CDP WebSocket directly?
Use the short-lived automation credential issued for that session. The business key authenticates lifecycle HTTP requests.
Q: Why can the dashboard see a session while the worker gets 403?
The dashboard and worker can act with different identities and workspace selections. Confirm that the worker's key has access to the session's workspace.
Q: What does a successful session lookup prove?
It proves that the service request could read a session. Browser readiness, CDP authorization, and successful completion of a website task have their own checks.
Q: Can I reuse connection details after a disconnect?
Inspect the original session. If it remains ready, request fresh details and use the new endpoint and header.
Q: Does disconnecting Playwright stop the managed session?
End the session through the owning workflow and wait for ended. A client disconnect leaves lifecycle cleanup to the owner.
Marcus Chen
Nov. 19th 2026
Launch cloud browsers on demand
Handle fingerprints and CAPTCHAs
Automate workflows and power AI agents
From web scraping and testing to AI-driven automation, run it all in the cloud.