Authentication

Authenticating to the API

All endpoints under /api/v1 require an API key. Keys are generated from your dashboard and scoped to your account’s plan limits.

Creating an API key

  1. Sign in to your dashboard.
  2. Navigate to Account → API keys.
  3. Click Generate key, provide a descriptive name, and copy the value immediately.
  4. Store the key securely. For safety, rotate keys regularly and revoke unused ones.

The plaintext value is shown only once at creation. If you lose it, revoke the old key and create a new one.

Sending the API key

Include the key with every request using one of the supported header formats. We recommend the bearer style for consistency. 

Authorization: Bearer <API_KEY>
Authorization: ApiKey <API_KEY>
X-API-Key: <API_KEY>

A legacy ?api_key= query parameter is accepted but should be avoided outside of quick testing because URLs can be logged in plain text.

Example request

curl https://xuptimemonitor.com/api/v1/monitors \
  -H "Authorization: Bearer <API_KEY>"

Replace <API_KEY> with your generated value. Responses with status 401 indicate the key is missing, malformed, or revoked.

Rate limits & usage headers

Every authenticated response includes headers so you can monitor monthly consumption relative to the limit provided by your plan (plan.config.api.requestLimit).

HeaderDescription
X-API-LimitMaximum requests allowed for the current billing month. unlimited when no cap applies.
X-API-UsageTotal requests performed by your account this month.
X-API-RemainingRequests remaining before the limit is reached (only present when a limit exists).
X-API-ResetUTC timestamp when the usage counter resets (first day of the next month).
X-API-Key-UsageRequests performed this month with the specific API key that made the call.

When the limit is exceeded, the API returns 429 Too Many Requests along with Retry-After signalling how many seconds remain until the counter resets.

Error responses

401 Unauthorized

{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "data": {
    "reason": "API key missing or invalid"
  }
}

Double-check the header name and ensure the key has not been revoked.

429 Too Many Requests

{
  "statusCode": 429,
  "statusMessage": "Monthly API request limit exceeded",
  "data": {
    "limit": 100000,
    "usage": 100000,
    "resetsAt": "2025-02-01T00:00:00.000Z"
  }
}

Wait until the counter resets or upgrade your plan to increase the monthly allowance.