Credentials

Docs

Credentials

Authenticate with password-protected pages using Basic Auth credentials.

The credentials field allows you to capture snapshots of pages protected by HTTP Basic Authentication. This is commonly used for staging environments, internal tools, and preview deployments.

Schema

Field	Type	Required	Notes
`name`	`string`	Yes	Username for Basic Auth.
`pass`	`string`	Yes	Password for Basic Auth.

How It Works

When credentials are provided:

The browser sends an Authorization header with the Base64-encoded credentials
The header is included in the initial page request and all subsequent requests to the same origin
Protected resources (images, scripts, stylesheets) on the same domain are also authenticated

Example Request

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://staging.example.com/"
    ],
    "viewports": [
      { "width": 1280, "height": 800 }
    ],
    "credentials": {
      "name": "staging-user",
      "pass": "staging-password"
    }
  }' \
  "https://api.watchero.io/api/v1/snapshots"

Common Use Cases

Staging Environments

Capture screenshots of password-protected staging sites before production deployment:

{
  "urls": ["https://staging.myapp.com/"],
  "credentials": {
    "name": "reviewer",
    "pass": "review-2024"
  }
}

Preview Deployments

Access branch preview URLs that require authentication (common with Vercel, Netlify, etc.):

{
  "urls": ["https://feature-branch-123.preview.myapp.com/"],
  "credentials": {
    "name": "preview",
    "pass": "auto-generated-token"
  }
}

Limitations

Limitation	Description
Basic Auth only	Form-based login, OAuth, and cookie-based sessions are not supported.
Single origin	Credentials are sent only to the domain in the URL. Cross-origin resources are not authenticated.
No MFA	Multi-factor authentication flows cannot be automated.

Handling Authentication Failures

If credentials are invalid or missing for a protected page, the snapshot job will fail with an error indicating the authentication issue. Check the job status response for details:

{
  "id": "cmhdgfak60002mdtxnen6g2qi",
  "status": "FAILED",
  "error": "HTTP 401 Unauthorized"
}

To troubleshoot:

Verify credentials work manually with curl -u name:pass https://url
Ensure the page uses HTTP Basic Auth (not form-based login)
Check if the protection applies to the specific path being captured

Block Options Metadata