Monitoring password-protected pages: Basic Auth and custom headers

A regular Tracker.ru check reaches your site anonymously — like a new visitor with no login and no cookies. If a page is password-protected, the server responds with 401 Unauthorized and the monitor marks it as down. To check protected areas — an admin panel, a customer account, an API or a staging server — add sign-in credentials to the monitor settings.

There are two options, and you can combine them:

• HTTP Basic Auth — a login and password for sites where the browser shows a system sign-in dialog (this is how auth_basic in nginx and .htpasswd in Apache work).
• Custom request headers — up to 10: an API token (Authorization: Bearer …), a key (X-Api-Key), a session cookie (Cookie) or any other header your server expects.

Which plans include it

Authentication is available on the paid Basic and Pro plans and during the trial. On the Free plan the form is replaced with a short description and a link to pricing.

How to set it up

1. Open the monitor in your dashboard and click "Edit".
2. Make sure the address starts with https:// — credentials are sent over HTTPS only.
3. Find the "Authorization" section (HTTP monitors only).
4. For Basic Auth, fill in "Login" and "Password".
5. For a header, click "Add header" and enter a name and value, for example Authorization and Bearer eyJhbGciOi…. Repeat for other headers.
6. Click "Save". Starting with the next check, the monitor sends the credentials.

Tip. Create a separate read-only account or token for monitoring. If you ever need to rotate it, your main access is not affected, and the monitor has no extra permissions.

How the login, password and headers are stored

• The password and header values are stored encrypted and are used only for checks.
• Once saved, they are never shown again — neither in the dashboard nor in API responses. Instead of the password you will see "Password is set", instead of a header value — "Value is set". The login and header names are visible to the monitor owner.
• To keep a saved password or value, leave the field empty. To replace it, enter a new one.
• "Remove login and password" removes Basic Auth, the trash icon removes a header row, "Remove authorization" removes everything. Changes apply after you save.
• Only the monitor owner can change authentication. People you share the monitor with only see that authentication is configured.

How this data is stored and used is described in the Terms of Service.

If you change the server address

The saved password and header values are tied to the server address — scheme, domain and port. If you change the domain, subdomain or port, the form asks you to enter the password and header values again. This way credentials never go to another server without you knowing. The login and header names are kept. Changing the path or query on the same server (/admin → /admin/health) does not require re-entering anything.

Limits

Certificate validation

For monitors with authentication, Tracker.ru first validates the server's SSL certificate and only then sends the password and headers. If the certificate is self-signed, expired, issued for another domain, or the server does not send the full certificate chain, credentials are not sent and the monitor goes down with an SSL error. This check cannot be disabled: otherwise the password could reach whoever impersonates the server.

Certificates issued by the Russian Trusted Root CA (Ministry of Digital Development) are trusted — such sites are checked as usual.

Watch out for incomplete chains: a browser often fetches the missing intermediate certificate on its own and opens the site without errors, while a monitor with authentication does not. See SSL errors for how to find and fix this.

Russian regions only

Monitors with authentication are checked from Russia only — currently the "Moscow" region. Other regions are unavailable in the settings of such a monitor. If a non-Russian region is already selected, authentication cannot be saved: remove that region first. Read more about regions in multi-region monitoring.

If you see the warning "Monitor is not checked: a region in Russia is required", select the "Moscow" region or remove authentication.

Redirects

If the server redirects the check, the password and headers are sent only while the address stays on the same server: the same https scheme, domain and port. On a redirect to another domain, subdomain, port or to http://, credentials are not sent on that and all following hops. If a protected page redirects to a sign-in page on another domain, monitor the final address instead.

Forbidden headers

Some headers are set by the service itself and cannot be overridden: Host, Content-Length, Transfer-Encoding, TE, Trailer, Expect, Connection, Keep-Alive, Upgrade, User-Agent, Accept-Encoding and every header starting with Proxy-.

You can set the Authorization header on its own — for example, for a Bearer token. But it is not allowed together with a Basic Auth login and password: use either a login and password or the Authorization header.

Screenshots are taken without authentication

If screenshots are enabled for the monitor, they are taken without the login, password or headers. A screenshot of a protected page will most likely show a sign-in dialog or a 401 page — this is expected and does not affect the monitor status.

Order of steps with quick add

With quick add from the monitor list, the monitor is created right away and starts checking without authentication, and then the edit form opens. A protected page responds with 401. By default a down alert is sent after the second consecutive failed check, so if you don't save the login, password or headers before it, you will get a down notification. Once authentication is saved, the next check succeeds and you get a recovery notification.

To avoid the false alarm:

• fill in the "Authorization" section in the edit form right after adding the monitor and save, or
• create the monitor via the API with credentials in a single request (example below).

What happens when you switch to Free

If your plan expires or you move to Free, monitors with authentication are turned off. The login, password and headers are kept. A banner appears above the form saying the monitor is off because authentication is available on the Basic and Pro plans.

Then you have two options:

• Pay for Basic or Pro — these monitors are turned back on automatically.
• Remove authentication — the monitor can then be turned on in Free and will check the page without a password.

While a monitor has authentication, you cannot turn it on manually in Free. Read more in what happens at the end of the paid period.

Via the API

Authentication fields are available when creating and updating a monitor (POST /api/urls, PUT /api/urls/{id}), HTTP monitors only:

Create a monitor with authentication right away:

curl -X POST https://tracker.ru/api/urls \
  -H "Authorization: Bearer <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "admin.example.com/health",
    "protocol": "https",
    "monitor_type": "http",
    "period": 60,
    "basic_auth_user": "monitor",
    "basic_auth_password": "<password>",
    "custom_headers": [
      {"name": "X-Api-Key", "value": "<key>"}
    ]
  }'

The first Authorization header in this request is your Tracker.ru API token; it has nothing to do with the checked site.

The response contains no password and no header values — only flags that they are set:

{
  "has_basic_auth": true,
  "basic_auth_user": "monitor",
  "custom_headers_count": 1,
  "custom_headers": [
    {"name": "X-Api-Key", "has_value": true}
  ]
}

basic_auth_user and custom_headers are visible to the monitor owner only; has_basic_auth and custom_headers_count — to everyone with access to the monitor.

How updates work:

• On update, custom_headers replaces the whole set. To keep the value of a saved header, send its name without value. A new name without a value returns an error.
• If you change the server address (domain, port or scheme), send the password and header values again, otherwise the request returns an error.
• Switching the monitor to TCP removes authentication.

Example: replace the key and keep the cookie unchanged.

curl -X PUT https://tracker.ru/api/urls/123 \
  -H "Authorization: Bearer <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_headers": [
      {"name": "X-Api-Key", "value": "<new_key>"},
      {"name": "Cookie"}
    ]
  }'

FAQ

Why does a monitor with authentication still show 401?

Check the login, password or token — they may have expired or been changed on the server. If the server expects a token in a header but you set Basic Auth (or vice versa), it will also respond with 401. Read more in 401 Unauthorized.

Why does the monitor fail with an SSL error when the site opens in a browser?

For monitors with authentication the certificate is validated more strictly than in a browser: an incomplete chain, a self-signed or expired certificate is rejected, and the password is not sent. Fix the certificate on the server and the monitor recovers on its own.

Can a protected page be checked from Frankfurt or Minsk?

No. Monitors with authentication are checked from Russian regions only.

Where can I see the saved password?

Nowhere: once saved, the password and header values are never shown. If you forgot it, set a new one in the form or via the API.

See also

• How to add a website to monitoring
• Keyword check — make sure the protected page opened, not a sign-in form
• SSL certificate errors
• Page screenshots