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
scopeiswrite(create and change endpoints and filters) orread. Ask forwriteto set up endpoints.client_nameis optional, up to 60 characters. The person sees it when approving, so name yourself and the project.
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.
2. Show the person the code and the link
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
- Put it in the project's secret store as
HOLE_MONITOR_API_KEY: a.envfile that is git-ignored, the CI secret store, or the platform's secret manager. - Never commit it, print it, log it or include it in a summary.
- Send it as
Authorization: Bearer <key>tohttps://api.holemonitor.live.
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
- Each approved agent gets its own key, named after the agent and the code, under API keys in the dashboard. Revoke it there at any time.
- Approving counts against your plan's API key limit.
- Every approval and denial is recorded in the account's audit log.
- Discovery metadata is at
/.well-known/oauth-authorization-server.