How to monitor REST APIs with authentication
Monitor an authenticated REST API with checks that log in the way a client does, call real endpoints with the token, and assert on the response body, not just the status code. Add a response-time limit and alerts for 401s and 429s. Vigil's API flow chains the login and the calls, passing the token between steps.
What can go wrong with REST APIs with authentication
- Auth is down, API is up. The token endpoint or identity provider fails, so every client gets 401 while a health route without auth stays green.
- 200 with an error inside. The API returns
200 {"error": …}or an empty list after a backend failure. Status-code monitoring misses it. - Schema drift. A deploy renames or removes a field; the endpoint works, the clients break.
- Slow, not down. p95 creeps from 200 ms to 3 s as a table grows or a dependency degrades; timeouts start at the clients.
- Rate limiting. A noisy client or a retry storm pushes everyone into 429s.
- Expired credentials. An API key or client certificate used by integrations expires on a date nobody tracked.
The signals that matter, with alert thresholds
| Signal | Alert when | Why it matters |
|---|---|---|
| Login step | non-2xx or no token in the response | Nobody can authenticate. |
| Status of core endpoints | not the expected code | Broken. |
| Body assertions | field missing or wrong value | Errors and schema drift. |
| Response time | > your SLA (e.g. 800 ms) | Slow is down for clients with timeouts. |
| 401 / 429 rates | above normal | Auth or rate-limit trouble. |
Thresholds are starting points. Tune them after a week of data: an alert nobody acts on should be raised or removed.
How to check REST APIs with authentication by hand
TOKEN=$(curl -s -X POST https://auth.example.com/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials | jq -r .access_token)
curl -sS -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me -w '\n%{http_code} %{time_total}s\n'
curl -sI -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me | grep -i ratelimit
curl -s -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me | jq -e '.id' >/dev/null && echo ok
How to watch REST APIs with authentication with Vigil
- For a static key, create an API check in New monitor: method, URL, headers (
Authorization: Bearer …), expected status and a response-time limit. - Add assertions, one per line:
json data.id exists,json data.items[0].status == active,header content-type contains application/json,not_contains "error". - For tokens that expire, create an API flow: step 1 posts to the token endpoint and extracts
access_tokenwith a JSON path into{{token}}; step 2 calls the API withAuthorization: Bearer {{token}}; more steps can create and delete a test record. Values can also be extracted from headers or with a regex. - Use a dedicated low-privilege monitoring account, and add domain and certificate monitoring for the API host.
- Every failure keeps its evidence (status, headers, timings, the first 4 KB of the body) and is confirmed by a second check 12 seconds later before anyone is alerted.
Every alert goes to the channels you pick: email, Slack, Telegram, Discord, Microsoft Teams, Pushover, webhooks or on-call paging. Failures are confirmed by a second check before anyone is woken up.
REST APIs with authentication monitoring FAQ
Should monitoring use a real user's credentials?
No. Create a dedicated account with the least privilege that can still exercise the endpoints, so its credentials are useless for anything else and its traffic is easy to filter.
How do I monitor GraphQL with this?
The same way: POST the query as the body with Content-Type: application/json and assert on json data…. Also assert not_contains "errors", because GraphQL returns errors with HTTP 200.
How often should API checks run?
Every 1 to 5 minutes for customer-facing APIs. Failures are confirmed with a retry before alerting, so a shorter interval does not mean more false alarms.