---
title: "Authentication"
description: "GitHub OAuth, API key format, rotation, and common auth errors."
doc_version: "1"
last_updated: "2026-06-02"
---

## GitHub OAuth flow

UptimeMonitoring uses GitHub OAuth exclusively. No email, no password.

1. Visit [app.uptimemonitoring.com](https://app.uptimemonitoring.com)
2. Click "Sign in with GitHub"
3. Authorize the UptimeMonitoring app
4. You're in — create your first API key

## API key format

All API keys use the `umk_live_` prefix followed by a random string:

```bash
Authorization: Bearer umk_live_abc123def456...
```

The prefix makes keys easy to identify in logs and secret scanners.

## Multiple keys by environment

Use separate keys for different environments and tools:

- `ci-prod` — for GitHub Actions and deploy pipelines
- `local-dev` — for development and testing
- `mcp-claude` — for your MCP integration
- `mcp-cursor` — for Cursor

Each account supports up to 10 API keys.

## Rotation and grace window

When you rotate a key:

1. A new key is issued immediately
2. The old key remains valid for a 5-minute grace window
3. After grace, the old key is permanently revoked

This prevents downtime during key rotation in automated systems.

## Common auth errors

The error envelope is flat: `{"error": "<message>"}`. Match on the HTTP status; the message is the literal validator output.

| Status | Message | Meaning |
|--------|---------|---------|
| 401 | `missing authorization` | `Authorization` header absent |
| 401 | `invalid credentials` | API key not recognised or revoked |
| 403 | `account suspended; contact support` | Account suspended (e.g. by the port-scan heuristic). Returned on regular `/api/v1/*` calls. |
| 403 | `forbidden` | Admin-only route hit by a non-admin caller. Opaque on purpose — does not disclose whether the route exists. |

Note: 401 responses currently carry `Content-Type: text/plain` even though the body is valid JSON. Parse the body as JSON regardless; this discrepancy is being fixed on the API side (see [monitive/uptimemonitoring-api](https://github.com/monitive/uptimemonitoring-api)).