> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.scrapybara.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.scrapybara.com/_mcp/server.

# Auth States

## What are auth states?

Auth states in Scrapybara allow you to capture, save, and reuse website authentication data across browser sessions. This feature is extremely useful for:

* Automating login flows
* Persisting authentication between browser instances
* Avoiding repetitive login procedures in your automation scripts
* Testing authenticated features without manual intervention

Auth states capture cookies, local storage, session storage, and other browser-based authentication data.

## Save auth state

When you've successfully authenticated with a website in the browser, you can save the authentication state for future use. Each auth state is identified by a unique ID and an optional name (defaults to "default" if not specified).

#### Python

```python
# First, create a browser instance
instance = client.start_browser()

# Open the stream, navigate to the login page, and log in
webbrowser.open(instance.get_stream_url().stream_url)
```

Once you've logged in, you can save the auth state with a name:

```python
# Now save the auth state with a name
auth_state_id = instance.save_auth(name="example_site").auth_state_id
print(f"Saved auth state ID: {auth_state_id}")
```

#### TypeScript

```typescript
// First, create a browser instance
const instance = await client.startBrowser();

// Open the stream, navigate to the login page, and log in
window.open(instance.getStreamUrl().streamUrl, "_blank");
```

Once you've logged in, you can save the auth state with a name:

```typescript
// Now save the auth state with a name
const authStateId = await instance.saveAuth({name: "example_site"}).authStateId;
console.log(`Saved auth state ID: ${authStateId}`);
```

## Modify auth state

If you have an existing auth state that you want to update with new authentication data, you can use the `modify_auth` functionality. This is useful when credentials have changed or when an existing auth state needs to be refreshed.

#### Python

```python
# First, create a browser instance
instance = client.start_browser()

# Open the stream, navigate to the login page, and log in with new credentials
webbrowser.open(instance.get_stream_url().stream_url)
```

Once you've logged in, you can modify the auth state with a new name:

```python
# Update an existing auth state with the new credentials
# You can optionally provide a new name
instance.modify_auth(auth_state_id="your_existing_auth_state_id", name="renamed_auth_state")
```

#### TypeScript

```typescript
// First, create a browser instance
const instance = await client.startBrowser();

// Open the stream, navigate to the login page, and log in with new credentials
window.open(instance.getStreamUrl().streamUrl, "_blank");
```

Once you've logged in, you can modify the auth state with a new name:

```typescript
// Update an existing auth state with the new credentials
// You can optionally provide a new name
await instance.modifyAuth({
  authStateId: "your_existing_auth_state_id", 
  name: "renamed_auth_state"
});
```

## Load auth state

Once you've saved an auth state, you can use it to authenticate future browser sessions without going through the login process again:

#### Python

```python
# Create a new browser instance
instance = client.start_browser()

# Authenticate using a previously saved auth state
instance.authenticate(auth_state_id="your_auth_state_id")
```

#### TypeScript

```typescript
// Create a new browser instance
const instance = await client.startBrowser();

// Authenticate using a previously saved auth state
await instance.authenticate({authStateId: "your_auth_state_id"});
```

## Using auth states in the playground

The Scrapybara Playground provides a visual interface for managing auth states:

1. **Create an auth state**:
   * Head to the Scrapybara [auth](https://scrapybara.com/auth) page
   * Click on the "Create auth state" button
   * Log in to the website and save the auth state

2. **Use an existing auth state**:
   * Click the fingerprint icon next to the instance dropdown menu
   * Choose your saved auth state from the dropdown
   * When you start the instance, it will automatically apply the authentication data

## Best practices

Here are some best practices for working with auth states:

1. **Use descriptive names**: Name your auth states clearly (e.g., "github\_login" or "shopify\_admin") for easy identification.

2. **Refresh regularly**: Authentication tokens can expire. Consider updating your auth states periodically using the `modify_auth` functionality.

3. **Test before use**: Always verify that your auth state is still valid before relying on it for critical automation.

4. **Multiple auth states**: Maintain separate auth states for different environments (e.g., production, staging, development).