# auth.md
This service supports agentic registration for AI agents.

Resource Server: https://haiwaizhijia.com
Authorization Server: https://haiwaizhijia.com

## Discover
1. Look for `WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource"` header on 401, or fallback to `/.well-known/oauth-protected-resource`.
2. Fetch Protected Resource Metadata to read `resource`, `authorization_servers`, `scopes_supported`.
3. Fetch `/.well-known/oauth-authorization-server` to read `issuer`, `token_endpoint`, `grant_types_supported` and the `agent_auth` block.

## Pick a method
- You have a session that can be exchanged for ID-JAG bound to this service: use `identity_assertion`
- You only have user's email: use `service_auth`
- Neither: use `anonymous` (pre-claim, start working immediately)

## Register

### identity_assertion
```http
POST /agent/identity HTTP/1.1
Host: haiwaizhijia.com
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion": "<ID-JAG JWT>",
  "client_id": "your-agent-client-id"
}
```
Response: `identity_assertion`, `assertion_expires`, `scopes`.

### service_auth
```http
POST /agent/identity HTTP/1.1
Content-Type: application/json

{
  "type": "service_auth",
  "login_hint": "user@example.com"
}
```
Returns `claim_token` + `claim` block with `user_code` and `verification_uri`.

### anonymous
```http
POST /agent/identity HTTP/1.1
Content-Type: application/json

{
  "type": "anonymous"
}
```
Returns pre-claim `identity_assertion` + `claim_token`.

## Claim ceremony
1. **Get materials**: `service_auth` already returns `claim` block. For `anonymous`, POST `/agent/identity/claim`.
2. **Hand off**: Surface `verification_uri` and `user_code` to user. User opens link and enters code on this site.
3. **Poll**: POST `/oauth2/token` with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=...`. Returns `authorization_pending` until complete.

## Exchange the assertion
```http
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https://haiwaizhijia.com
```

## Use the access_token
```
Authorization: Bearer <access_token>
```
When access_token expires, re-exchange same assertion. No refresh_token.

## Errors
- `invalid_issuer`, `invalid_signature`, `expired`, `invalid_audience` -> fix assertion
- `authorization_pending` -> keep polling
- `invalid_grant` -> restart registration

## Revocation
POST access_token to `/oauth/revoke` (RFC 7009). Assertion survives. Provider may revoke assertion via SET event.

---
Generated by Agent Ready plugin for Haiwaizhijia (海外之家) | Direct U.S. Real Estate Developers &amp; Texas Villa Investments - https://haiwaizhijia.com