Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Agent Tooling (71)

Automation workflows, orchestration references, and developer tooling guides.

agent-tooling/.agents/skills/agent-browser/references/authentication.md 5,023 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

Authentication Patterns

Related: session-management.md for state persistence details, SKILL.md for quick start.

Basic Login Flow
Saving Authentication State
Restoring Authentication
OAuth / SSO Flows
Two-Factor Authentication
HTTP Basic Auth
Cookie-Based Auth
Token Refresh Handling
Security Best Practices

bash

# Navigate to login page
agent-browser open https://app.example.com/login
agent-browser wait --load networkidle

# Get form elements
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"

# Fill credentials
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"

# Submit
agent-browser click @e3
agent-browser wait --load networkidle

# Verify login succeeded
agent-browser get url  # Should be dashboard, not login

Saving Authentication State

After logging in, save state for reuse:

bash

# Login first (see above)
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"

# Save authenticated state
agent-browser state save ./auth-state.json

Restoring Authentication

Skip login by loading saved state:

bash

# Load saved auth state
agent-browser state load ./auth-state.json

# Navigate directly to protected page
agent-browser open https://app.example.com/dashboard

# Verify authenticated
agent-browser snapshot -i

OAuth / SSO Flows

For OAuth redirects:

bash

# Start OAuth flow
agent-browser open https://app.example.com/auth/google

# Handle redirects automatically
agent-browser wait --url "**/accounts.google.com**"
agent-browser snapshot -i

# Fill Google credentials
agent-browser fill @e1 "user@gmail.com"
agent-browser click @e2  # Next button
agent-browser wait 2000
agent-browser snapshot -i
agent-browser fill @e3 "password"
agent-browser click @e4  # Sign in

# Wait for redirect back
agent-browser wait --url "**/app.example.com**"
agent-browser state save ./oauth-state.json

Two-Factor Authentication

Handle 2FA with manual intervention:

bash

# Login with credentials
agent-browser open https://app.example.com/login --headed  # Show browser
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

# Wait for user to complete 2FA manually
echo "Complete 2FA in the browser window..."
agent-browser wait --url "**/dashboard" --timeout 120000

# Save state after 2FA
agent-browser state save ./2fa-state.json

HTTP Basic Auth

For sites using HTTP Basic Authentication:

bash

# Set credentials before navigation
agent-browser set credentials username password

# Navigate to protected resource
agent-browser open https://protected.example.com/api

Manually set authentication cookies:

bash

# Set auth cookie
agent-browser cookies set session_token "abc123xyz"

# Navigate to protected page
agent-browser open https://app.example.com/dashboard

Token Refresh Handling

For sessions with expiring tokens:

bash

#!/bin/bash
# Wrapper that handles token refresh

STATE_FILE="./auth-state.json"

# Try loading existing state
if [[ -f "$STATE_FILE" ]]; then
    agent-browser state load "$STATE_FILE"
    agent-browser open https://app.example.com/dashboard

    # Check if session is still valid
    URL=$(agent-browser get url)
    if [[ "$URL" == *"/login"* ]]; then
        echo "Session expired, re-authenticating..."
        # Perform fresh login
        agent-browser snapshot -i
        agent-browser fill @e1 "$USERNAME"
        agent-browser fill @e2 "$PASSWORD"
        agent-browser click @e3
        agent-browser wait --url "**/dashboard"
        agent-browser state save "$STATE_FILE"
    fi
else
    # First-time login
    agent-browser open https://app.example.com/login
    # ... login flow ...
fi

Security Best Practices

Never commit state files - They contain session tokens

bash

   echo "*.auth-state.json" >> .gitignore

Use environment variables for credentials

bash

   agent-browser fill @e1 "$APP_USERNAME"
   agent-browser fill @e2 "$APP_PASSWORD"

Clean up after automation

bash

   agent-browser cookies clear
   rm -f ./auth-state.json

Use short-lived sessions for CI/CD

bash

   # Don't persist state in CI
   agent-browser open https://app.example.com/login
   # ... login and perform actions ...
   agent-browser close  # Session ends, nothing persisted

Repository Docs & Knowledge Base

Categories

Agent Tooling (71)

Authentication Patterns

Contents

Saving Authentication State

Restoring Authentication

OAuth / SSO Flows

Two-Factor Authentication

HTTP Basic Auth

Token Refresh Handling

Security Best Practices

Repository Docs & Knowledge Base

Categories

Agent Tooling (71)

Authentication Patterns

Contents

Basic Login Flow

Saving Authentication State

Restoring Authentication

OAuth / SSO Flows

Two-Factor Authentication

HTTP Basic Auth

Cookie-Based Auth

Token Refresh Handling

Security Best Practices