# auth.md

## Superclock agent authentication

Superclock supports agent authentication via the auth.md protocol.

### endpoints

- POST https://superclock.app/agent/auth — register an agent

### anonymous registration

```
POST https://superclock.app/agent/auth
Content-Type: application/json

{ "type": "anonymous" }
```

response:

```json
{
  "ok": true,
  "data": {
    "credential": "sk_...",
    "user_id": "usr_...",
    "claim_token": "ct_...",
    "scopes": ["public"]
  }
}
```

### claiming by link (your person allows it where they are signed in)

step 1 — ask for a link:

```
POST https://superclock.app/agent/auth/claim/link
Content-Type: application/json

{ "claim_token": "ct_..." }
```

response:

```json
{ "ok": true, "data": { "claim_url": "https://superclock.app/connect/K7QX-2M4P", "code": "K7QX-2M4P", "expires_in": 600 } }
```

step 2 — show claim_url to your person. they open it where they are signed in to Superclock and allow or refuse. it works once, for ten minutes.

step 3 — check:

```
GET https://superclock.app/agent/auth/claim/link?claim_token=ct_...
```

`status` is waiting, allowed, refused or expired. once allowed, your SAME credential carries: alarms.read, alarms.write.

### scopes

- anonymous: public
- claimed: alarms.read, alarms.write
- human (OAuth): all scopes

### using credentials

include the credential in the Authorization header:

```
Authorization: Bearer sk_...
```

MCP server: https://mcp.superclock.app/mcp (the same Bearer credential).
before a claim: what_superclock_can_do only; every other tool answers with how to be claimed.
after your person allows you: their alarms and timers (alarms.read, alarms.write). removing an alarm always asks them first.
protected resource metadata: https://mcp.superclock.app/.well-known/oauth-protected-resource/mcp

### discovery

- GET https://superclock.app/.well-known/oauth-protected-resource
- GET https://superclock.app/.well-known/oauth-authorization-server