jackwener/OpenCLI · error · AuthRequiredError

LinkedIn messaging API authentication failed:

Error message

LinkedIn messaging API authentication failed:

What it means

The CLI replays the captured messaging API request from the page context with the session's CSRF token. If the fetch response reports authRequired, an AuthRequiredError is thrown with LinkedIn's own error detail appended. This means LinkedIn's API itself rejected the credentials even though the page looked signed in.

Source

Thrown at clis/linkedin/inbox.js:198

      throw new CommandExecutionError(
        'LinkedIn did not issue a messaging API request; the inbox may have failed to load.',
      );
    }

    const cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
    const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
    if (!jsession) {
      throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn.');
    }
    const csrf = jsession.replace(/^"|"$/g, '');

    // Widen the page size to the requested limit where the query supports it.
    const targetUrl = located.url.replace(/count:\d+/, 'count:' + limit);
    const fetched = unwrapEvaluateResult(
      await page.evaluate(`(${fetchMessagingApi.toString()})(${JSON.stringify(targetUrl)}, ${JSON.stringify(csrf)})`),
    );
    if (fetched && fetched.authRequired) {
      throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn messaging API authentication failed: ' + fetched.error);
    }
    if (!fetched || fetched.error || !fetched.json) {
      throw new CommandExecutionError(
        'LinkedIn messaging API returned an unexpected response: ' + ((fetched && fetched.error) || 'no data'),
      );
    }

    let conversations = parseConversations(fetched.json, located.mailboxUrn || '');
    if (unreadOnly) conversations = conversations.filter((c) => c.unread);
    if (conversations.length === 0) {
      if (unreadOnly) return [];
      throw new EmptyResultError('linkedin inbox', 'No LinkedIn conversations were found in the inbox.');
    }

    return conversations.slice(0, limit).map((c, index) => ({
      rank: index + 1,
      thread_url: threadUrl(c.thread_id),
      thread_id: c.thread_id,

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Re-authenticate: sign in again in the automated browser profile to refresh JSESSIONID/li_at, then retry.
  2. Confirm the CSRF token derivation matches the current JSESSIONID (quotes stripped) — re-running after a fresh login fixes stale-token cases.
  3. Reduce request frequency / back off if LinkedIn is throttling the account.
  4. Check fetched.error in the message for the exact API complaint (e.g. 403 challenge) and address it (e.g. complete a security challenge manually).

Example fix

// before
inbox(); // AuthRequiredError: API authentication failed (stale session)

// after: refresh session, then retry with backoff
await refreshLinkedinSession(profile);
await retry(inbox, { attempts: 2, retryOn: AuthRequiredError });
Defensive patterns

Strategy: retry

Validate before calling

// ensure a fresh session and matching CSRF before the API-backed command
const cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
if (!jsession || sessionOlderThan(jsessionTimestamp(), MAX_SESSION_AGE)) {
  await reloginLinkedin(profile);
}

Type guard

const isApiAuthFailure = (e) => e instanceof AuthRequiredError && /messaging API authentication failed/i.test(e?.message || '');

Try / catch

try {
  return await linkedinInbox();
} catch (e) {
  if (isApiAuthFailure(e)) {
    await refreshLinkedinSession(profile);
    return retry(linkedinInbox, { attempts: 2 });
  }
  throw e;
}

Prevention

When it happens

Trigger: fetchMessagingApi(targetUrl, csrf) returns { authRequired: true, error: ... } when called during `linkedin inbox` — e.g. the API responded 401/403 or a login redirect payload.

Common situations: JSESSIONID stale relative to the li_at session (partial logout), CSRF token mismatch after cookie rotation, LinkedIn rate-limiting/challenging the account, or the API endpoint requiring a renewed session.

Understand the failure class

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/d41696e571863da0. Report an issue: GitHub.