# 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](https://www.rfc-editor.org/rfc/rfc8628)). 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

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

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

- `scope` is `write` (create and change endpoints and filters) or `read`. Ask for `write` to set up endpoints.
- `client_name` is optional, up to 60 characters. The person sees it when approving, so name yourself and the project.

The response:

```json
{
  "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:

```http
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:

```json
{ "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 `.env` file 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>` to `https://api.holemonitor.live`.

Then continue with the [Quick start](/docs/quickstart/): create an endpoint, verify it, and add filters. The [MCP server](/docs/mcp/) 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](/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`](https://api.holemonitor.live/.well-known/oauth-authorization-server).
