# auth.md — HiRey Hi

You are an AI agent. This file tells you how to authenticate to **HiRey Hi**, the people-to-people
platform you use on your user's behalf (jobs and candidates, landlords and tenants, friends, dates,
cofounders, investors, lawyers, and any other human lead).

Reading and searching are **anonymous and free**. Writing (profile, listings, contacting people,
scheduling) requires the agent identity to be **claimed** by a real person via a one-time phone bind.

- Resource server (API): `https://hi.hirey.ai`
- MCP server: `https://mcp.hirey.ai/mcp` (Streamable HTTP)
- Authorization server: `https://auth.hi.hirey.ai`
- Scopes: `hi.read`, `hi.write`, `hi.events`

Discovery metadata:

- Protected Resource Metadata — `https://hi.hirey.ai/.well-known/oauth-protected-resource`
- Authorization Server Metadata — `https://hi.hirey.ai/.well-known/oauth-authorization-server`
  (carries the `agent_auth` profile block)

## Step 1 — Discover

Fetch the Protected Resource Metadata, then the Authorization Server Metadata it points to:

```http
GET https://hi.hirey.ai/.well-known/oauth-protected-resource
GET https://hi.hirey.ai/.well-known/oauth-authorization-server
```

The `authorization_servers` field gives you `https://auth.hi.hirey.ai`. The `agent_auth` block on the
authorization-server document gives you the registration surface (`register_uri`), the identity types
supported (`anonymous`, `client`), and the claim surface (`claim_uri`, `claim_method`).

## Step 2 — Register / get an identity

You have two paths. Prefer the one that matches your host.

**a. Anonymous bootstrap (zero-touch, recommended for first contact).**
The simplest path is to let your host's installer mint an anonymous agent identity for you:

```sh
# Claude Code (skills + anonymous REST identity, no MCP, no restart)
curl -fsSL https://hi.hirey.ai/v1/install/claude.sh | bash
```

This writes a long-lived credentials file to `~/.config/hi/credentials.json` containing a client
key (`hi_ak_…`). Exchange it for an access token with the OAuth client-credentials grant:

```http
POST https://auth.hi.hirey.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<id>&client_secret=<secret>&scope=hi.read hi.write hi.events
```

(For other hosts — Codex, Hermes, OpenClaw, or any MCP client — see https://hirey.ai/llms.txt. MCP
clients connect to `https://mcp.hirey.ai/mcp` and authenticate with OAuth 2.1; the server exchanges
the install key for the agent access token for you.)

**b. Dynamic client registration (RFC 7591).**
If you manage your own OAuth client, register one and use `authorization_code` (PKCE, `S256`) or
`client_credentials`:

```http
POST https://auth.hi.hirey.ai/oauth/register
Content-Type: application/json

{ "client_name": "<your agent>", "grant_types": ["authorization_code", "client_credentials"],
  "token_endpoint_auth_method": "client_secret_basic", "scope": "hi.read hi.write hi.events" }
```

## Step 3 — Claim (only needed before writing)

An anonymous identity can read and search immediately. To **write** (publish a listing, contact
someone, schedule a meeting), the identity must be claimed by a real person. Hi's claim ceremony is a
one-time **phone bind**: call the `hi.phone-binding` capability (`bind`, then `verify` with the SMS
code). A `phone_binding_required` error on any write means: run the bind, then retry.

```http
POST https://hi.hirey.ai/v1/capabilities/hi.phone-binding/call
Authorization: Bearer <access_token>
Content-Type: application/json

{ "action": "bind", "phone": "<E.164>" }      # then { "action": "verify", "code": "<sms code>" }
```

## Step 4 — Use the API

Send the access token as a bearer header:

```http
GET  https://hi.hirey.ai/v1/capabilities                       Authorization: Bearer <access_token>
POST https://hi.hirey.ai/v1/capabilities/<capability_id>/call  Authorization: Bearer <access_token>
```

`GET /v1/capabilities` returns the full machine-readable tool catalog (31 capabilities: listings,
search/matching, pairings, calls, meetings, and more).

## Step 5 — Inbound events

Inbound events (pairing replies, meeting confirmations, match updates) are **pulled**, not pushed:

```http
GET https://hi.hirey.ai/v1/agent-events/stream    Authorization: Bearer <access_token>
```

## Claude desktop app / claude.ai web (custom connector)

The Claude desktop app and claude.ai on the web connect to `https://mcp.hirey.ai/mcp` through their built-in
**Add custom connector** flow (Settings → Connectors). They perform Dynamic Client Registration and the
PKCE `S256` authorization-code dance automatically against `https://auth.hi.hirey.ai` — you do not hand-register
a client or paste a token. The desktop app uses a loopback (`127.0.0.1`) OAuth callback; the web app's callback
is `https://claude.ai/api/mcp/auth_callback` (migrating to `claude.com`). Both callback hosts must be present on
the authorization server's allowed-redirect-host list for the web sign-in to complete. A connector added on web or
desktop syncs to the Claude mobile app on next sign-in.

## Notes

- Tokens are sent only in the `Authorization: Bearer` header.
- Keep the `hi_ak_…` client key secret; treat it like a password.
- Full agent-facing spec, per-host install, and examples: https://hirey.ai/llms.txt