Authentication

Overview

A monitor that gets a 401 is a monitor that reports an outage that isn’t one. Every HTTP and gRPC monitor can therefore carry credentials of its own, chosen in the Authentication block of the create modal and the edit panel.

Method	What is sent	Available on
Basic auth	Authorization: Basic <user:password>	HTTP, gRPC
Bearer token	Authorization: Bearer <token>	HTTP, gRPC
API key	A named header, or a URL query parameter	HTTP, gRPC (header only)
Session cookie	A raw Cookie header	HTTP, gRPC
OAuth2 client credentials	A token fetched from your IdP, then Bearer	HTTP
Client certificate (mTLS)	A client certificate during the TLS handshake	HTTP

Database, SMTP, IMAP and Redis monitors authenticate with their own user/password pair instead — see Databases and Mail & cache.

Where the secrets live

Every secret on this page is encrypted at rest, in a column separate from the monitor’s URL. Reading a monitor back — through the dashboard, the public API, the audit log or a GDPR export — returns the method and its non-secret settings (the token endpoint, the header name, the client id) with the secret itself replaced by ***.

That mask is also what the edit form receives. Leave a masked field as it is and the stored value is kept; type something else and it is replaced. This is why you never have to re-enter a token to change an unrelated setting.

An API key placed in the URL query is masked wherever the URL is displayed or logged, the same way https://user:password@host credentials are moved out of the URL on save.

Bearer token

The most common case: a static token issued by the service you monitor.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Paste the token alone — OKStatus adds the Bearer prefix.

API key

Two forms, because services are split between them:

• Header — X-API-Key: <key>, or whatever name the service expects.
• URL parameter — ?api_key=<key>, appended to the monitor’s URL on every check.

Prefer the header form when the service accepts both: a key in a URL ends up in the target’s own access logs, which is out of our reach.

Session cookie

For an endpoint that only answers to a logged-in browser session. Paste the raw content of the Cookie header:

session=abc123; csrf=def456

A session cookie expires — usually within hours or days. When it does, the checks start failing with the login page’s status code. Use it for a short-lived diagnostic, not as a permanent setup; OAuth2 or an API key is the durable answer.

OAuth2 client credentials

For an API behind Entra ID, Keycloak, Auth0, Okta or any OAuth2 authorization server supporting the client_credentials grant (RFC 6749 §4.4).

Setting	Description
Token endpoint	e.g. https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Client ID	The application’s identifier
Client secret	Stored encrypted
Scope	Optional — api://monitoring/.default, read:status…
Audience	Optional — required by Auth0, ignored by most others
Credentials sent as	client_secret_basic (HTTP Basic header, the default) or client_secret_post (form body)

Before each check, the region agent requests a token and keeps it until it expires (30 s of margin). A monitor running every 30 seconds from five regions therefore asks your IdP for a handful of tokens per hour, not fourteen thousand a day.

If the token endpoint itself fails, the check fails with an explicit OAuth2 authentication failed: … message naming the token endpoint — an IdP outage is not an outage of the monitored service, and the two are not debugged in the same place.

Client certificate (mTLS)

For an endpoint that requires a client certificate: internal APIs, banking, health, IoT.

Setting	Description
Client certificate	PEM. Public by nature, stored encrypted anyway
Private key	PEM, unencrypted PKCS#8. Stored encrypted, never returned by the API
Certificate authority	PEM, optional — for an internal PKI whose CA is not publicly trusted

A passphrase-protected key is refused at save time rather than accepted and then silently unusable: the region agents present the certificate through native-tls, which cannot decrypt one. Convert it first:

openssl pkcs8 -topk8 -nocrypt -in encrypted.key -out monitoring.key

The server’s own certificate is still validated against the public roots (or the CA you provide). Skip TLS certificate validation on the monitor turns that check off, which also applies to the mTLS connection.

gRPC monitors

gRPC checks send the same credentials as metadata: Basic, Bearer, an API key in a header, or a cookie. Two forms have no equivalent and are refused explicitly rather than silently ignored:

• an API key in a query parameter — a gRPC call has no query string;
• OAuth2 and mTLS — not wired to the gRPC channel yet.

What it does not cover

AWS SigV4, self-signed JWTs, per-request HMAC signatures, NTLM and Kerberos are not available yet. Reusable credentials shared across monitors (define once, reference from many) are on the roadmap; today, each monitor carries its own.