# Books TBR - auth.md

Authentication, registration, and API consumption specification for Autonomous Agents and AI Systems (Agent Readiness Discovery per Auth.md Standard & RFC 9727).

---

## 1. Audience and Purpose

This document describes how AI agents, autonomous tools (LLM Tool Calling), crawlers, and automated systems can interact with, authenticate, and register to use the **Books TBR** APIs.

- **Website:** [https://bookstbr.com](https://bookstbr.com)
- **OpenAPI 3.1 Specification:** [https://bookstbr.com/api/openapi.json](https://bookstbr.com/api/openapi.json)
- **Documentation:** [https://bookstbr.com/api/docs](https://bookstbr.com/api/docs)
- **API Catalog (RFC 9727):** [https://bookstbr.com/.well-known/api-catalog](https://bookstbr.com/.well-known/api-catalog)

---

## 2. Access Tiers and Supported Methods

Books TBR supports three access modes:

### A. Public Anonymous Access (No Authentication)
Agents can query the following endpoints without prior credentials:
- `GET /api/search?q={query}&engine={all|archive|drive|maravillosos}&format={all|pdf|epub}&page={1}`
- `GET /api/by-slug/{slug}`
- `GET /api/suggestions`
- `GET /api/recent-searches?limit={5}`
- `GET /api/ai-summary?title={title}&author={author}`
- `GET /api/health`

### B. Anonymous Agent Registration (`anonymous`)
Agents wishing to identify themselves for higher rate limits can request an agent session token via the registration endpoint.
- **Identity Type:** `anonymous`
- **Credential Type:** `bearer_token`
- **Claim URI:** `https://bookstbr.com/agent/claim`

### C. Identity Assertion & ID-JAG (`identity_assertion`)
For enterprise or user-delegated agents presenting signed assertions:
- **Assertion Types:** `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`
- **Credential Types:** `bearer_token`, `api_key`
- **Claim URI:** `https://bookstbr.com/agent/claim`
- **Revocation URI:** `https://bookstbr.com/agent/revoke`

---

## 3. Agent Registration & Provisioning Endpoints

### Agent Registration (`POST /agent/auth`)
Allows an agent to register and obtain session credentials.

```http
POST /agent/auth HTTP/1.1
Host: bookstbr.com
Content-Type: application/json

{
  "agent_name": "MySearchBot/1.0",
  "identity_type": "anonymous"
}
```

**Successful Response (`200 OK`):**
```json
{
  "status": "registered",
  "token_type": "Bearer",
  "access_token": "btbr_agent_token_anon_demo",
  "expires_in": 86400,
  "scopes": ["search:books", "read:books", "ai:summary"]
}
```

### Claim Validation (`POST /agent/claim`)
Endpoint to bind or verify an agent identity (e.g., verified email or ID-JAG assertion).

```http
POST /agent/claim HTTP/1.1
Host: bookstbr.com
Content-Type: application/json

{
  "assertion_type": "verified_email",
  "email": "agent-operator@example.com"
}
```

### Credential Revocation (`POST /agent/revoke`)
Allows immediate revocation of an issued token or session.

```http
POST /agent/revoke HTTP/1.1
Host: bookstbr.com
Content-Type: application/json

{
  "token": "btbr_agent_token_..."
}
```

---

## 4. Using Credentials in API Requests

Agents with registered credentials should send their token via the standard HTTP `Authorization` header:

```http
GET /api/search?q=The+Great+Gatsby HTTP/1.1
Host: bookstbr.com
Authorization: Bearer <access_token>
```

---

## 5. OAuth & PRM Discovery Metadata

- **OAuth Protected Resource Metadata (RFC 9470):**
  `https://bookstbr.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414):**
  `https://bookstbr.com/.well-known/oauth-authorization-server`
