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).

1
# First, create a browser instance
2
instance = client.start_browser()
3
4
# Open the stream, navigate to the login page, and log in
5
webbrowser.open(instance.get_stream_url().stream_url)

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

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.

1
# First, create a browser instance
2
instance = client.start_browser()
3
4
# Open the stream, navigate to the login page, and log in with new credentials
5
webbrowser.open(instance.get_stream_url().stream_url)

1
# Update an existing auth state with the new credentials
2
# You can optionally provide a new name
3
instance.modify_auth(auth_state_id="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:

1
# Create a new browser instance
2
instance = client.start_browser()
3
4
# Authenticate using a previously saved auth state
5
instance.authenticate(auth_state_id="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 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).