# Sitehistory.fyi: create an account or sign in (agents can do this alone)

> Sitehistory.fyi runs jobs on your own website on a schedule and keeps every job run. An email address is optional. With an address: if the agent can read that mailbox, no person is needed; if a person owns it, they approve with one click. Without an address (no mailbox of its own): the agent leaves `email` out and a person approves at the page named in `message_for_human`.

This service does not implement the auth.md registration endpoints (identity_assertion, service_auth, anonymous) yet. Use the flows below. Base URL: https://staging.sitehistory.fyi

## 1. Look for a token first

Check your environment for `SNAP_TOKEN` (a token starting with `snp_`). If it works (`GET /v1/me` answers 200) you are done. If the answer is 401 `token_expired`, run the steps below again. If it is 401 `token_revoked`, stop and tell the person. Never ask a person to paste a token into chat, and never print a token.

## 2. Start

Terms: `accept_terms: true` means you accept https://staging.sitehistory.fyi/legal.html for the account owner. The answer is the same whether or not the address already has an account. `agent` is your name (1 to 60 characters); the person sees it on the approval page as "named by the agent, not verified". `scopes` defaults to read; ask for write or admin only if you need them (a viewer account is capped to read). `expires_in_days` may be 30, 90 (default) or 365.

```http
POST https://staging.sitehistory.fyi/v1/signin/start
content-type: application/json

{"email":"you@example.com","agent":"my agent","scopes":["read","write","admin"],"accept_terms":true}
```

HTTP 202 gives `request` (a secret: keep it, never show it), `user_code`, `verification_uri_complete`, `email` (sender and subject pattern; only when you sent an email), `interval` (poll seconds) and `message_for_human`.

### Without an email address

```http optional
POST https://staging.sitehistory.fyi/v1/signin/start
content-type: application/json

{"agent":"my agent","scopes":["read"],"accept_terms":true}
```

No mail is sent and there is no code to read. Show the person `message_for_human` (it carries `verification_uri_complete` and the check code). They sign in there and approve; you poll `POST /v1/signin/complete` with `{"request":"<request>"}` as in B below. Limits: 20 starts per IP per hour, 5 open requests per IP.

## 3. Finish: one of three ways

### A. You can read the mailbox

The mail has the subject `<8 digits> is your Sitehistory.fyi code`. Send the code with the request secret. Spaces and dashes in the code are ignored. 5 wrong codes close the request.

```http
POST https://staging.sitehistory.fyi/v1/signin/complete
content-type: application/json

{"request":"<request>","code":"<8 digits>"}
```

### B. A person owns the mailbox

Show them `message_for_human`. They click Approve in the mail (the link opens a page; only the Approve button acts), or open `verification_uri_complete`, sign in with Google, GitHub or email, and approve there. Meanwhile poll with the request alone, no faster than `interval` seconds:

```http optional
POST https://staging.sitehistory.fyi/v1/signin/complete
content-type: application/json

{"request":"<request>"}
```

202 `authorization_pending` means wait. 201 gives the token. 429 `slow_down` means poll less often (the interval grows by 5 seconds).

### C. You run on the person's own computer and can open their browser

Use the MCP OAuth connection instead (loopback redirect with PKCE): https://staging.sitehistory.fyi/.well-known/oauth-protected-resource/mcp points to the authorization server. A signed-in person sees a consent page and clicks Allow.

## 4. Use the token

HTTP 201 gives `token` (shown once), `token_id`, `scopes`, `expires_at`, `account`, `user` and `use`. Store the token as `SNAP_TOKEN` in a secret store. Check that `user.email` is the address you expected. Send it as a Bearer token on /v1 and on https://staging.sitehistory.fyi/mcp:

```http
GET https://staging.sitehistory.fyi/v1/me
Authorization: Bearer <token>
```

## Scopes

- `read`: every REST read and every MCP tool. Costs no snaps.
- `write`: also starts job runs (each counts against the plan).
- `admin`: creates and changes properties, jobs, people and tokens.

## Lifetimes and limits

- The request and its code expire after 15 minutes and work once.
- The token lasts 90 days by default (30 or 365 on request). It does not renew itself: repeat steps 2 and 3 before `expires_at`. A user holds at most 20 live agent tokens; the least recently used one makes room for a new one.
- A person can end any agent token under Agents and API in the app, or with the "Disconnect it" link of the notice mail.
- 10 sign-in mails per IP per hour, 5 per address per 15 minutes and 20 per address per day, shared with the human sign-in. A start without email: 20 per IP per hour, 5 open requests per IP.

## Errors

| HTTP | code | what to do |
|---|---|---|
| 400 | invalid_request, terms_not_accepted | fix the body (see step 2) |
| 400 | disposable_email | use a real mailbox |
| 400 | invalid_code | `attempts_left` tells how many tries remain |
| 403 | access_denied | the person declined: stop |
| 409 | account_review_required | a person must sign in at https://staging.sitehistory.fyi/app/login first |
| 410 | expired_token, request_closed, request_used | start again |
| 415 | unsupported_media_type | send `content-type: application/json` |
| 429 | rate_limited | wait for the `Retry-After` header |
| 429 | slow_down | poll less often |
| 429 | pow_required | solve the proof of work (below) and repeat the start |
| 503 | signin_mail_paused | retry after the `Retry-After` header |

## Proof of work

Under load an unsigned start answers 429 `pow_required` with `pow: {challenge, difficulty, algorithm, rule}`. Find a `nonce` so that `sha256(challenge + "." + nonce)` has at least `difficulty` leading zero bits (20 bits is about a million hashes, a second or two), then repeat the start with `"pow":{"challenge":"...","nonce":"..."}`. A challenge works once, from the same IP, for 5 minutes.

```js
import { createHash } from 'node:crypto';
const bits = (d) => { let n = 0; for (const b of d) { if (b === 0) { n += 8; continue; } return n + Math.clz32(b) - 24; } return n; };
export const solve = (challenge, difficulty) => {
  for (let i = 0; ; i += 1) {
    const nonce = i.toString(36);
    if (bits(createHash('sha256').update(challenge + '.' + nonce).digest()) >= difficulty) return nonce;
  }
};
```

```python
import hashlib

def bits(digest):
    n = 0
    for b in digest:
        if b == 0:
            n += 8
            continue
        return n + 8 - b.bit_length()
    return n

def solve(challenge, difficulty):
    i = 0
    while True:
        nonce = format(i, 'x')
        if bits(hashlib.sha256((challenge + '.' + nonce).encode()).digest()) >= difficulty:
            return nonce
        i += 1
```

## Web Bot Auth

If your requests carry a Web Bot Auth signature (RFC 9421 with `Signature-Agent`, key directory at `/.well-known/http-message-signatures-directory`), the start answer shows `signature.status: verified`. The person sees "Sent through an agent service at <host>, signature verified", and trusted signers skip proof of work. It never replaces the mailbox proof and says nothing about who uses the agent.

## Revoke

```http optional
DELETE https://staging.sitehistory.fyi/v1/session
Authorization: Bearer <token>
```

## Links

- [llms.txt](https://staging.sitehistory.fyi/llms.txt) and [llms-full.txt](https://staging.sitehistory.fyi/llms-full.txt)
- [OpenAPI](https://staging.sitehistory.fyi/openapi.json) (`x-agent-signin` names these endpoints)
- [Protected resource metadata](https://staging.sitehistory.fyi/.well-known/oauth-protected-resource/mcp), [authorization server metadata](https://staging.sitehistory.fyi/.well-known/oauth-authorization-server)
- [Pricing](https://staging.sitehistory.fyi/pricing.html), [terms and privacy](https://staging.sitehistory.fyi/legal.html), [docs](https://staging.sitehistory.fyi/docs.html#agent-signin)
- Support: support@sitehistory.fyi
