Hole Monitor

Agent setup

A coding agent gets its own Hole Monitor API key through a device sign-in (OAuth 2.0 Device Authorization Grant, RFC 8628). The person approves the request in their browser. The key goes straight to the agent; nobody copies or pastes it.

If you are an agent, follow these steps in order.

1. Ask for a code

POST https://api.holemonitor.live/oauth/device
Content-Type: application/x-www-form-urlencoded

scope=write&client_name=Claude%20Code%20in%20acme%2Fweb

The response:

{
  "device_code": "Zp3…",
  "user_code": "WXYZ-BCDF",
  "verification_uri": "https://holemonitor.live/activate/",
  "verification_uri_complete": "https://holemonitor.live/activate/?user_code=WXYZ-BCDF",
  "expires_in": 600,
  "interval": 5
}

Keep device_code to yourself. It is what you exchange for the key.

Tell them, in these words or close to them:

Open https://holemonitor.live/activate/?user_code=WXYZ-BCDF, sign in if asked, check that the code shown is WXYZ-BCDF, and approve.

The code expires after 10 minutes. The person chooses read or write access when approving, which may differ from what you asked for.

3. Poll for the key

Every interval seconds (5), until you get a key or a final error:

POST https://api.holemonitor.live/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=Zp3…
Response Meaning What to do
200 with access_token Approved Store the key (step 4). It is returned once
400 authorization_pending Not decided yet Wait interval seconds and poll again
400 slow_down You polled too fast Add 5 seconds to your interval
400 access_denied The person denied it, or the account is at its key limit Stop and tell the person the error_description
400 expired_token The 10 minutes ran out Start again at step 1
400 invalid_grant Unknown or already used device_code Start again at step 1

A success looks like:

{ "access_token": "hm_…", "token_type": "Bearer", "scope": "write" }

4. Store the key

Then continue with the Quick start: create an endpoint, verify it, and add filters. The MCP server accepts the same key, and MCP clients can also sign in to it themselves through the same approval page.

For the person