Reusing Context & Auth

How to Reuse Authentication Across Steel Sessions

The Steel Sessions API provides a contexts endpoint that allows you to capture and transfer browser state (including cookies and local storage) between sessions. This is particularly useful for maintaining authenticated states across multiple sessions, helping your AI agents access protected resources efficiently without repeatedly handling login processes or exposing credentials at all.

In this guide, you'll learn how to use the Steel Sessions API to reuse authentication between browser sessions.

For an easier way to reuse authentication, context, cookies, extensions etc. consider using Steel's new Profiles API. It utilizes auth context alongside a complete browser profile to automatically reuse all your auth, not just context or cookies.

For additional practical examples and recipes, check out the Steel Cookbook.

Prerequisites

Terminal
$ 
npm install steel-sdk

Overview of the Process

Reusing authentication across sessions involves a straightforward workflow:

  • Create and authenticate an initial session. Create a Steel session, navigate to target websites, and authenticate (log-in, etc).

  • Capture the session context. Extract browser state data through the GET /v1/sessions/{id}/context endpoint. This endpoint returns a context object containing browser state information such as cookies and local storage. Example:

    Typescript
    1
    const initialSessionContext = await client.sessions.context(initialSession.id);

  • Reuse session context in new sessions. Create new sessions using the captured context object by passing it directly to the sessionContext parameter. Example:

    Typescript
    1
    const session = await client.sessions.create({ sessionContext: initialSessionContext });

    Now your new session will begin with the same authenticated state as your previous session without having to manually authenticate again.

Complete Example (Playwright, Node.js)

Note: While this example uses TypeScript, Node.js, and Playwright, the same logic applies regardless of your programming language or automation framework. The Steel API handles the context management - you just need to capture and reuse it using your preferred tools.

The following script demonstrates the entire authentication reuse process. It:

  • Creates an initial session and authenticates with a webesite by logging in

  • Captures the authenticated session context

  • Creates a new session using the captured context

  • Verifies the authentication was successfully transferred to the new session

Typescript
1
import { chromium, Page } from "playwright";

2
import Steel from "steel-sdk";

3
import dotenv from "dotenv";

4


5
dotenv.config();

6


7
const client = new Steel({

8
  steelAPIKey: process.env.STEEL_API_KEY,

9
});

10


11
// Helper function to perform login

12
async function login(page: Page) {

13
  await page.goto("https://practice.expandtesting.com/login");

14
  await page.fill('input[name="username"]', "practice");

15
  await page.fill('input[name="password"]', "SuperSecretPassword!");

16
  await page.click('button[type="submit"]');

17
}

18


19
// Helper function to verify authentication

20
async function verifyAuth(page: Page): Promise<boolean> {

21
  await page.goto("https://practice.expandtesting.com/secure");

22
  const welcomeText = await page.textContent("#username");

23
  return welcomeText?.includes("Hi, practice!") ?? false;

24
}

25


26
async function main() {

27
  let session;

28
  let browser;

29


30
  try {

31
    // Step 1: Create and authenticate initial session

32
    console.log("Creating initial Steel session...");

33
    session = await client.sessions.create();

34
    console.log(

35
      `\x1b[1;93mSteel Session #1 created!\x1b[0m\n` +

36
        `View session at \x1b[1;37m${session.sessionViewerUrl}\x1b[0m`

37
    );

38


39
    // Connect Playwright to the session

40
    browser = await chromium.connectOverCDP(

41
      `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}`

42
    );

43


44
    const page = await browser.contexts()[0].pages()[0];

45
    await login(page);

46


47
    if (await verifyAuth(page)) {

48
      console.log("✓ Authentication successful");

49
    }

50


51
    // Step 2: Capture and transfer authentication

52
    const sessionContext = await client.sessions.context(session.id);

53


54
    // Clean up first session

55
    await browser.close();

56
    await client.sessions.release(session.id);

57
    console.log("Session #1 released");

58


59
    // Step 3: Create new authenticated session

60


61
    session = await client.sessions.create({ sessionContext });

62
    console.log(

63
      `\x1b[1;93mSteel Session #2 created!\x1b[0m\n` +

64
        `View session at \x1b[1;37m${session.sessionViewerUrl}\x1b[0m`

65
    );

66


67
    // Connect to new session

68
    browser = await chromium.connectOverCDP(

69
      `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}`

70
    );

71


72
    // Verify authentication transfer

73
    const newPage = await browser.contexts()[0].pages()[0];

74
    if (await verifyAuth(newPage)) {

75
      console.log("\x1b[32m✓ Authentication successfully transferred!\x1b[0m");

76
    }

77
  } catch (error) {

78
    console.error("Error:", error);

79
  } finally {

80
    // Cleanup

81
    await browser?.close();

82
    if (session) {

83
      await client.sessions.release(session.id);

84
      console.log("Session #2 released");

85
    }

86
  }

87
}

88


89
main().catch(console.error);

Check out the full example

Important Considerations

  • Cookie and JWT Based Authentication Only: This method works exclusively with websites that utilize cookie-based or JWT-based authentication (saved onto Local Storage).

  • Enhancing Continuity: A useful practice is to save the URL of the last visited page along with the session context. This allows you to restore the browsing context, providing continuity for users.

  • Session Security: Treat captured contexts as sensitive data. Ensure proper security and regularly refresh your sessions to maintain account integrity.

  • Available for Live Sessions: Context can only be captures from live sessions. So if you wish to re-use a context, make sure to grab the object before releasing the session.

Contents

PrerequisitesOverview of the ProcessComplete Example (Playwright, Node.js)Important Considerations