# auth.md — Tianji Yao Agent Registration & Authentication

You are an AI agent or autonomous system. Tianji Yao (天机爻 - https://tianjiyao.com) is a modern Chinese metaphysics and AI divination service offering computational engines and specialized analysis APIs:
- **BaZi (Four Pillars of Destiny)**: Full natal chart calculation, 10-year great life stages (大运), annual cycles (流年), Shensha, and elemental balances (`/api/bazi`).
- **I Ching (周易六爻)**: Six-line hexagram casting, changing lines, transformed hexagrams, and judgment interpretation (`/api/divination`).
- **Tarot Reading**: Single card, 3-card spread, and Celtic Cross divination (`/api/tarot`).
- **Zi Wei Dou Shu (紫微斗数)**: 12-palace astrological chart plotting, star brightness, and transformations (`/api/ziwei`).
- **Dream Interpretation (周公解梦)**: Traditional Chinese dream symbolism and psychology synthesis (`/api/dream`).

This document describes how autonomous agents and AI tools discover, register, and authenticate to access Tianji Yao API services without human intervention.

---

## Canonical Metadata Discovery

Tianji Yao publishes standard OAuth 2.0 and agent discovery metadata:

- **Auth.md Skill Document**: `https://tianjiyao.com/auth.md`
- **Protected Resource Metadata (PRM)**: `https://tianjiyao.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata**: `https://tianjiyao.com/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery**: `https://tianjiyao.com/.well-known/openid-configuration`
- **RFC 9727 API Catalog**: `https://tianjiyao.com/.well-known/api-catalog`
- **OpenAPI 3.1 Specification**: `https://tianjiyao.com/openapi.json`
- **Developer Documentation**: `https://tianjiyao.com/docs/api.html`

---

## Component Status

| Component | Status | URL / Endpoint |
| :--- | :--- | :--- |
| `auth.md` Standard | Live | `https://tianjiyao.com/auth.md` |
| Protected Resource Metadata (PRM) | Live | `/.well-known/oauth-protected-resource` |
| OAuth Authorization Server | Live | `/.well-known/oauth-authorization-server` |
| Agent Self-Registration (`register_uri`) | Live | `/api/agent/register` |
| Agent Token Verification / Claim | Live | `/api/agent/claim` |
| Service Health Status | Live | `/api/health` |

---

## Authentication Methods

Tianji Yao APIs use standard HTTP Bearer token authentication:

```http
GET /api/bazi HTTP/1.1
Host: tianjiyao.com
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
```

When an unauthenticated or unauthorized request is made, Tianji Yao responds with HTTP 401 and standard `WWW-Authenticate` response headers:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://tianjiyao.com/.well-known/oauth-protected-resource"
```

---

## Agent Registration Flows

Autonomous agents can obtain credentials via either **Anonymous Self-Registration** or **Identity Assertion**:

### Flow 1: Anonymous Self-Registration (Recommended for autonomous agents)

Autonomous agents can call the registration endpoint to immediately acquire a scoped agent token with default free quota:

```http
POST /api/agent/register HTTP/1.1
Host: tianjiyao.com
Content-Type: application/json

{
  "client_name": "MyAutonomousAgent/1.0",
  "identity_type": "anonymous",
  "requested_scopes": ["read", "divination", "bazi", "tarot", "ziwei"]
}
```

Response:

```json
{
  "token_type": "Bearer",
  "access_token": "tj_agent_live_9f83ac02741d...",
  "expires_in": 2592000,
  "scope": "read divination bazi tarot ziwei dream",
  "token": "tj_agent_live_9f83ac02741d..."
}
```

### Flow 2: Identity Assertion (`verified_email`)

Agents operating on behalf of a human user can register or link credentials using verified email identity assertions:

```http
POST /api/agent/register HTTP/1.1
Host: tianjiyao.com
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "verified_email",
  "email": "agent-user@example.com"
}
```

---

## Supported Scopes

The following scopes are supported across all Tianji Yao resource endpoints:

| Scope | Description |
| :--- | :--- |
| `read` | Read public service status and metadata |
| `divination` | Access I Ching hexagram casting and interpretation endpoints |
| `bazi` | Access Four Pillars natal chart calculation and reading engines |
| `tarot` | Access Tarot card draws and spread interpretations |
| `ziwei` | Access Zi Wei Dou Shu astrological palace and star computations |
| `dream` | Access traditional Chinese dream analysis |

---

## Error Handling

| HTTP Status | Error Code | Description |
| :--- | :--- | :--- |
| `400` | `invalid_request` | The request payload was malformed or missing required parameters |
| `401` | `invalid_token` | The provided Bearer token is missing, expired, or invalid |
| `403` | `insufficient_scope` | The token does not have permission for the requested scope |
| `429` | `rate_limit_exceeded` | The client exceeded allowed request rate; retry after `Retry-After` seconds |
| `500` | `server_error` | Internal processing error; retry with exponential backoff |