Authentication

Capture password-protected sites and authenticated content using various authentication methods.

Basic Authentication

For sites using HTTP Basic Auth, include credentials in the URL:

smippo https://username:password@example.com

The credentials are sent with every request using the Authorization header.

Cookie-Based Authentication

Most modern sites use cookies for authentication. You can export cookies from your browser and use them with Smippo.

Cookie File Format

Create a cookies.json file:

[
  {
    "name": "session_id",
    "value": "abc123xyz789",
    "domain": ".example.com",
    "path": "/",
    "httpOnly": true,
    "secure": true
  },
  {
    "name": "auth_token",
    "value": "eyJhbGciOiJIUzI1NiIs...",
    "domain": ".example.com",
    "path": "/"
  }
]

Using Cookies

smippo https://dashboard.example.com --cookies cookies.json

Getting Cookies from Browser

Chrome

1. Open DevTools (F12)
2. Go to Application → Storage → Cookies
3. Right-click and export, or manually copy values

Firefox

1. Open DevTools (F12)
2. Go to Storage → Cookies
3. Copy values to JSON format

Using an Extension

Cookie export extensions can export in JSON format compatible with Smippo:

• EditThisCookie (Chrome)
• Cookie Quick Manager (Firefox)

Custom Headers

Add authentication headers directly:

smippo https://api.example.com --headers '{"Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."}'

Multiple Headers

smippo https://example.com --headers '{
  "Authorization": "Bearer token123",
  "X-API-Key": "api-key-456",
  "X-Custom-Header": "value"
}'

Common Header Types

Interactive Authentication

For complex login flows (2FA, CAPTCHA, OAuth), use interactive authentication:

smippo https://secure.example.com --capture-auth

This opens a visible browser window where you can:

1. Navigate to the login page
2. Enter credentials manually
3. Complete 2FA/CAPTCHA
4. Once logged in, press Enter in the terminal
5. Smippo captures the authenticated session and continues

Interactive Auth Flow

smippo https://secure.example.com --capture-auth

  ╭─────────────────────────────────────────────╮
  │                                             │
  │  A browser window will open.                │
  │  Please log in, then press Enter here.      │
  │                                             │
  ╰─────────────────────────────────────────────╯

  [Browser opens, you log in]
  
  Press Enter when you've logged in...
  
  ✓ Session captured! Continuing capture...

When to Use Interactive Auth

• OAuth/SAML login flows
• Two-factor authentication
• CAPTCHA-protected logins
• Sites with complex JavaScript login forms

Proxy Authentication

For corporate proxies requiring authentication:

smippo https://example.com --proxy http://user:pass@proxy.corp.com:8080

Or with separate options:

smippo https://example.com \
  --proxy http://proxy.corp.com:8080 \
  --headers '{"Proxy-Authorization": "Basic dXNlcjpwYXNz"}'

Session Persistence

Captured sessions are stored in the manifest. When using smippo continue or smippo update, the same cookies/session are reused.

Export Captured Session

After an authenticated capture, cookies are stored in .smippo/manifest.json. You can extract and reuse them.

Session Expiry

Be aware that sessions expire. If your capture fails mid-way and you resume later, you may need to re-authenticate:

# Session expired, re-authenticate
smippo https://secure.example.com --capture-auth

Authentication Examples

Private Documentation

smippo https://docs.internal.company.com \
  --cookies work-cookies.json \
  --depth 5 \
  --scope subdomain

SaaS Dashboard

smippo https://app.saas.com/dashboard \
  --headers '{"Authorization": "Bearer <token>"}' \
  --depth 2 \
  --external-assets

Authenticated API Docs

smippo https://api.example.com/docs \
  --capture-auth \
  --depth 3 \
  --static

Corporate Intranet

smippo https://intranet.corp.com \
  --proxy http://proxy.corp.com:8080 \
  --cookies corp-session.json \
  --depth 5

Security Considerations

Credential Safety

• Don't commit cookies.json to version control
• Use environment variables for sensitive tokens
• Clear cookies after capture if not needed

Network Security

• Use HTTPS when possible
• Be cautious with --proxy on untrusted networks
• Interactive auth opens a real browser—be careful on shared machines

Session Cleanup

After capturing sensitive content:

# Remove session data
rm -rf ./site/.smippo/

Troubleshooting

"401 Unauthorized"

Your cookies/token may have expired. Re-export or use --capture-auth.

"Session Invalid After Redirect"

Some sites invalidate sessions on certain actions. Try:

smippo https://example.com --cookies fresh-cookies.json --wait-time 2000

"Can't Login with Interactive Auth"

Make sure you're clicking "Login" and waiting for the page to fully load before pressing Enter.

Next Steps

• Options Reference — All options explained
• Capture Command — Full capture reference
• Examples — Real-world authenticated captures