How to monitor an API that needs a login, with multi-step checks

Chain requests in one monitor: log in, save the access token, and use it to call the endpoints that matter, with JSON assertions on every step.

· 5 min read · By the Spot Downtime team

Many APIs don't take a fixed key. You log in first, get a short-lived access token, and send it with every request after that. A single-request monitor can't do that: any token you paste in expires within the hour. Multi-step API checks can. They run a short sequence of requests, carry values from one response into the next, and check each step along the way.

Multi-step API checks are part of the Starter and Pro plans.

The example

We'll monitor this flow, which is typical of OAuth-style and session-based APIs:

  1. POST /v1/auth/token with a username and password, which returns an access token.
  2. GET /v1/orders?limit=5 with that token, which should return a non-empty list.
Step 1 logs in and saves the token; step 2 sends it and checks the answer.

The login response looks like this:

json
{
  "data": {
    "access_token": "eyJhbGciOi…",
    "expires_in": 3600
  }
}

Use a dedicated account

Create a monitoring user with read-only access and nothing else. Its password is stored in the monitor and visible to everyone in your workspace, and it should never be able to change data.

Step 1: set up the login request

  1. Open Monitors, click Add monitor and choose API.
  2. Set Method to POST and URL to https://api.example.com/v1/auth/token.
  3. Under Headers, add Content-Type: application/json.
  4. In Body, add the credentials:
    json
    {"username": "uptime-monitor", "password": "…"}
  5. Set Expected status to 200.
  6. Add a JSON assertion: data.access_token exists. If login breaks, the check fails here with a clear reason.

Step 2: add the next step

Under More steps, add a step. Once there's a step, Save values for later steps appears on the first request. Save data.access_token as token.

Then fill in the new step:

  • Method GET, URL https://api.example.com/v1/orders?limit=5
  • Headers: Authorization: Bearer {{token}}
  • Expected status: 200
  • Assertion: data.orders.length greater than 0

On every check, {{token}} is replaced with the token from that check's login, so it never goes stale. You can use saved values in a step's URL, headers and body, and each step can save values of its own for the steps after it.

Step 3: save and watch the first run

Choose Check every and click Add monitor. The first check runs within a few seconds. If a step fails, the monitor shows which one and why: an unexpected status, a failed assertion, or a value that couldn't be found.

A failed check names the step and the reason.

Assertions you can use on each step

OperatorExampleCatches
equalsstatus equals okA health check that reports a problem
does not equaldata.state does not equal maintenanceA service stuck in maintenance mode
containsdata.region contains euTraffic routed to the wrong region
greater thandata.orders.length greater than 0Empty results from a broken query
less thandata.queue_depth less than 1000Workers falling behind
existsdata.access_token existsA login that silently stopped returning a token
does not existerror does not existErrors wrapped in a 200 response

Other flows worth a multi-step check

  • Create, read, delete. POST a test record, save its id, GET it back, then DELETE it. Proves writes work end to end. Use a test account so it never touches real data.
  • Search then fetch. Search for a known product, save the first result's ID, and load its detail page.
  • API key exchange. Swap a long-lived key for a short-lived token, then call a protected endpoint.

A monitor can have up to five steps after the first request. Keep flows short: each extra step is another thing that can be slow.

Watch the total time too

A login that takes three seconds hurts every user, not just your monitor. Turn on Alert when it's slow to get a warning when responses creep up; tracking API response times explains how to pick a threshold.

More in this series

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading