# HostHTML auth.md

This document tells AI agents how to register with and authenticate to the
HostHTML.Online REST API so they can create and manage hosted HTML pages.

## Audience

Automation and AI agents that want to programmatically manage HostHTML pages
via the REST API at `https://hosthtml.online/api/v1/*`.

## Registration

### Option 1 — Self-register (anonymous, no account)

`POST https://hosthtml.online/api/v1/agent/register`

Request body (JSON):

```json
{
  "name": "my-agent",
  "email": "optional-agent@example.com",
  "description": "Optional note about what this agent does"
}
```

Response `201 Created`:

```json
{
  "agent": { "id": "...", "name": "my-agent", "email": null },
  "api_key": "hh_live_...",
  "prefix": "hh_live_ab12",
  "usage": { "docs": "https://hosthtml.online/docs", "authmd": "https://hosthtml.online/auth.md" }
}
```

The `api_key` is returned **only once**. Store it in your secrets manager.

Rate limited to 5 registrations per IP per hour.

### Option 2 — Human-managed key

Sign in at https://hosthtml.online/profile and create an API key in the
"API Keys" section. Human keys are scoped to that account.

## Authentication

Send the key in the `Authorization` header:

```
Authorization: Bearer hh_live_...
```

or the legacy `X-API-Key: hh_live_...` header.

## Scopes

- `pages:read` — list and fetch your pages
- `pages:write` — create, update, and delete your pages

## Endpoints

| Method | Path                   | Auth | Description                     |
|--------|------------------------|------|---------------------------------|
| GET    | /api/v1/me             | yes  | Current principal               |
| GET    | /api/v1/pages          | yes  | List pages (q, limit, offset)   |
| GET    | /api/v1/pages/:id      | yes  | Get one page incl. content      |
| POST   | /api/v1/pages          | yes  | Create a page                   |
| PUT    | /api/v1/pages/:id      | yes  | Update a page                   |
| DELETE | /api/v1/pages/:id      | yes  | Delete a page                   |
| POST   | /api/v1/agent/register | no   | Self-register an agent          |

Full reference: https://hosthtml.online/docs

## Revocation

To revoke an agent key, delete the agent record via an admin or rotate the key
by registering a new agent. Human keys can be revoked from the Profile page.