Skip to main content

​
For AI Agent Users

This guide shows you how to authenticate your AI agents with websites that use Auth Agent. We’ll use the browser-use library as an example, which is the recommended way to integrate Auth Agent with your agents.

​
Overview

When your agent encounters a website that requires Auth Agent authentication:
  1. The agent navigates to the sign-in page
  2. Clicks the “Sign in with Auth Agent” button
  3. A spinning authentication page appears
  4. Your agent automatically authenticates using Auth Agent tools
  5. The website grants access and redirects to the dashboard

​
Step 1: Create Agent Credentials

1

Navigate to Agent Console

Go to https://auth-agent.com/console/agent
2

Create New Agent

Click “Create New Agent” and enter:
  • Your email address
  • Agent name (e.g., “My Shopping Assistant”)
3

Copy Credentials

Save your agent_id and agent_secret securely. You’ll need these to authenticate.
Keep your agent_secret secure! Never commit it to version control. Use environment variables.

​
Step 2: Install Dependencies

​
Install Browser-Use

Browser-use requires uv for installation: 
# Install uv (if not already installed)
pip install uv

# Create virtual environment
uv venv --python 3.12

# Activate environment
source .venv/bin/activate
# On Windows: .venv\Scripts\activate

# Install browser-use & chromium
uv pip install browser-use
uvx browser-use install

​
Install Auth Agent SDK

# Install Auth Agent SDK (includes browser-use integration)
uv pip install auth-agent-sdk

​
Step 3: Set Up Environment Variables

Create a .env file in your project: 
# Create .env file
touch .env
# On Windows: echo. > .env
Add your credentials to the .env file: 
# Auth Agent credentials
AGENT_ID=your_agent_id_here
AGENT_SECRET=your_agent_secret_here
AGENT_MODEL=browser-use  # or gpt-4, claude, etc.

# Browser-Use API key (get $10 free credits at https://cloud.browser-use.com/new-api-key)
BROWSER_USE_API_KEY=your_browser_use_api_key_here
We recommend using ChatBrowserUse which is optimized for browser automation (highest accuracy + fastest speed + lowest token cost). Get $10 free credits at https://cloud.browser-use.com/new-api-key

​
Step 4: Import Auth Agent Tools

The AuthAgentTools class is included in the SDK package. Simply import it: 
from auth_agent_sdk.agent import AuthAgentTools
If you get an ImportError, make sure you:
  • Installed the SDK: uv pip install auth-agent-sdk
  • Have version 2.5.2 or later: uv pip install --upgrade auth-agent-sdk

​
Step 5: Use in Your Agent

Create your agent script: 
import os
import asyncio
from dotenv import load_dotenv
from browser_use import Agent, ChatBrowserUse
from auth_agent_sdk.agent import AuthAgentTools

# Load environment variables
load_dotenv()

async def main():
    """Run the Auth Agent authentication example."""
    
    # Initialize LLM
    llm = ChatBrowserUse()
    
    # Initialize Auth Agent tools with credentials from environment
    tools = AuthAgentTools(
        agent_id=os.getenv('AGENT_ID'),
        agent_secret=os.getenv('AGENT_SECRET'),
        model=os.getenv('AGENT_MODEL', 'browser-use'),
    )
    
    # Create the task
    task = (
        "Go to https://example.com/ai-auth/login "
        "and click on the 'Sign in with Auth Agent' button. "
        "When the spinning authentication page appears (shows 'Authenticating AI Agent' with a spinner), "
        "use the authenticate_with_auth_agent tool to complete the authentication. "
        "Wait for the page to redirect after authentication succeeds. "
        "Keep waiting until you reach the dashboard page - do not stop until you see the dashboard. "
        "Only use the 'done' tool when you have successfully reached and verified you are on the dashboard page."
    )
    
    # Create and run the agent
    agent = Agent(
        task=task,
        llm=llm,
        tools=tools,  # Pass the Tools instance directly
    )
    
    # Run the agent
    history = await agent.run()
    
    print("\n" + "="*60)
    print("Authentication Complete!")
    print("="*60)
    print("\nFinal result:")
    print(history.final_result() if hasattr(history, 'final_result') else history)

if __name__ == "__main__":
    asyncio.run(main())

​
How It Works

1

Agent Navigates to Sign-In

Your agent goes to the website’s sign-in page
2

Clicks Auth Agent Button

The agent clicks “Sign in with Auth Agent”
3

Spinning Page Appears

The website shows a spinning authentication page with window.authRequest.request_id
4

Agent Authenticates

Your authenticate_with_auth_agent tool:
  • Extracts the request_id from the page
  • Calls Auth Agent API to authenticate
  • Waits for authentication to complete
5

Website Grants Access

The website receives the authorization code and creates a session
6

Redirect to Dashboard

The agent is redirected to the dashboard and can proceed with its task

​
What Happens Behind the Scenes

  1. Request ID Extraction: The tool reads window.authRequest.request_id from the page using JavaScript
  2. Authentication Request: The SDK sends a POST request to Auth Agent with your agent credentials
  3. Status Polling: The SDK polls the status endpoint until authentication completes
  4. Authorization Code: Once complete, the website receives an authorization code
  5. Token Exchange: The website exchanges the code for access tokens (happens server-side)
  6. Session Creation: The website creates a session based on the chosen integration scenario

​
Troubleshooting

Make sure the agent is on the spinning authentication page. The page should show “Authenticating AI Agent” with a spinner. The window.authRequest.request_id is only available on this specific page.
  • Verify your agent_id and agent_secret are correct
  • Check that your agent credentials are active in the console
  • Ensure the website is using Auth Agent (check the URL contains auth-agent.com)
The default timeout is 30 seconds. If authentication takes longer, the website may be slow. The page should still redirect automatically even if the tool times out.

​
Next Steps

Console Setup

Learn how to manage your agent credentials

API Reference

Complete API documentation for agent authentication

Examples

View more examples on GitHub

Support

Get help on GitHub