Scan authentication

What scan authentication is for

Some pages are not publicly reachable: staging environments, password-protected areas, internal tools or pages that are only served with a particular HTTP header. turbometrics can scan such pages too, if you pass the necessary credentials directly to the scan.

Typical scenarios:

• protecting a staging domain with HTTP basic auth and still measuring it regularly
• scanning content behind your own middleware that expects a particular header
• scanning a development environment without making it publicly available

Available authentication types

HTTP basic auth

Classic username-and-password authentication at the HTTP level. The browser prompt you know from password-protected directories.

Input:

• Username
• Password

turbometrics sends this data as an Authorization: Basic … header with every scan request.

HTTP header

Any header you want to send along with a value of your own. Suitable for token-based access control, your own middleware, feature flags or bypass mechanisms.

Input:

• Header name (e.g. Authorization, X-Access-Token, X-Preview-Key)
• Header value (the full value, e.g. Bearer abc123)

The header is transmitted exactly as you specify it.

Where you configure authentication

Single scan

For a manual scan – on the home page, under My scans and in the domain view – an Authentication area appears below the URL field, provided your plan includes the feature.

"None" is selected by default. If you choose HTTP basic auth or HTTP header, the matching fields appear.

The details apply to this one scan only. They are not stored permanently.

Scheduled scans

The form for scheduled scans (under Scheduled scans → Create a new scheduled scan and in the edit view of an existing target) has the same authentication area.

Here the details apply permanently to all automatically triggered scans of that target. With hourly, daily or weekly scans, the authentication is sent along automatically.

Password and header value when editing: When you edit an existing target, the password and header value are not pre-filled, for security reasons. If you leave the field empty, the value stored so far is kept. If you want to change the value, simply type the new one in.

Security and storage

Passwords and header values are stored encrypted and leave turbometrics only as an outgoing HTTP request to the scanned URL.

Scans with authentication are always treated as private. They do not appear in public scan lists and are not accessible via share links, unless you explicitly change the visibility to public. We recommend not making such scans public.

Plan dependency

Scan authentication is available from the Pro plan onwards.

Without the feature, the authentication area does not appear in the forms.

Limits and notes

• Exactly one authentication method per scan is supported: either basic auth or a header, not both at once.
• The authentication applies to the whole scan request, not to individual resources of a page (images, scripts and stylesheets are loaded separately and follow no separate authentication).
• If a scan fails despite stored authentication, check whether the credentials are correct and whether the page really expects that method.
• turbometrics follows HTTP redirects automatically – the authentication is sent along with redirects too.

Authentication via the API

Scans with authentication can also be triggered via the REST API. To do so, you pass an auth object in the request body of POST /api/v1/scans:

HTTP basic auth:

{
  "url": "https://staging.example.com",
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "secret"
  }
}

HTTP header:

{
  "url": "https://staging.example.com",
  "auth": {
    "type": "header",
    "header_name": "X-Preview-Key",
    "header_value": "abc123"
  }
}

The response contains auth_type as an indicator — credentials are never returned. The auth feature requires the Pro plan, just as in the web interface.

→ Full API documentation: REST API

Further reading

→ REST API → Scheduled scans → Scans → Plans & limits