# auth.md — Sarvadic Herbal Agent Registration & Authentication

## Overview

Welcome to the **Sarvadic Herbal Agent Authentication & Registration** specification. Sarvadic Herbal enables autonomous AI agents, personal shopping assistants, and commercial discovery systems to browse botanical products, register programmatically, and initiate purchases.

- **Issuer**: `https://sarvadicherbal.com`
- **Protected Resource Metadata**: `https://sarvadicherbal.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server**: `https://sarvadicherbal.com/.well-known/oauth-authorization-server`
- **OpenAPI 3.1 Spec**: `https://sarvadicherbal.com/openapi.json`
- **Target Audience**: Autonomous shopping agents, LLM tool executors, inventory aggregators, customer care bots.

---

## Agent Registration (`agent_auth`)

Agents can register autonomously without human intervention using standardized OAuth Authorization Server metadata extensions (`agent_auth`).

### Registration Endpoint

```http
POST https://sarvadicherbal.com/api/agent/auth
Content-Type: application/json
```

### Supported Registration Methods

1. **Anonymous Mode (`anonymous`)**:
   - Designed for instant guest access, price comparisons, and session-scoped shopping carts.
   - **Request Payload**:
     ```json
     {
       "identity_type": "anonymous",
       "client_name": "MyShoppingAgent/1.0",
       "capabilities": ["catalog:read", "order:create"]
     }
     ```
   - **Response**:
     ```json
     {
       "access_token": "sah_anon_eyJhbGciOi...",
       "token_type": "Bearer",
       "expires_in": 86400,
       "scope": "catalog:read order:create",
       "claim_uri": "https://sarvadicherbal.com/api/agent/claim"
     }
     ```

2. **Identity Assertion Mode (`identity_assertion`)**:
   - Supports cryptographically verified identity assertions:
     - `urn:ietf:params:oauth:token-type:id-jag` (Identity-JAG assertion)
     - `verified_email` (Agent operator verified email assertion)
   - **Request Payload**:
     ```json
     {
       "identity_type": "identity_assertion",
       "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
       "assertion": "<JWT-ASSERTION-TOKEN>",
       "client_name": "PersonalPurchasingAgent/2.0"
     }
     ```
   - **Response**:
     ```json
     {
       "access_token": "sah_auth_eyJhbGciOi...",
       "token_type": "Bearer",
       "expires_in": 2592000,
       "scope": "catalog:read order:create customer:profile",
       "claim_uri": "https://sarvadicherbal.com/api/agent/claim",
       "revocation_uri": "https://sarvadicherbal.com/api/agent/revoke"
     }
     ```

---

## User Claim Ceremony (`claim_uri`)

To bind an anonymous or newly provisioned agent session to a verified human customer profile:

```http
POST https://sarvadicherbal.com/api/agent/claim
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "customer_phone": "+916355299199",
  "customer_email": "customer@example.com",
  "verification_code": "123456"
}
```

Binding enables order history tracking, recurring Ayurvedic care refills, and personalized skin concern recommendations.

---

## Token Revocation (`revocation_uri`)

Agents or operators can revoke credentials at any time per RFC 7009:

```http
POST https://sarvadicherbal.com/api/agent/revoke
Content-Type: application/json

{
  "token": "<access_token>",
  "token_type_hint": "access_token"
}
```

---

## Credential Use

All authenticated API requests must include the Bearer token in the standard HTTP `Authorization` header:

```http
GET /api/catalog HTTP/1.1
Host: sarvadicherbal.com
Authorization: Bearer <access_token>
```

- **Bearer Methods Supported**: `header`
- **Supported Scopes**:
  - `catalog:read` — Read products, ingredients, stock status, pricing
  - `order:create` — Initiate orders, calculate shipping, generate payment requests
  - `customer:profile` — Access claimed customer preferences

---

## Public Unauthenticated Resources

For zero-setup querying, the following resources require **no authentication**:

| Resource | URL | Format / Protocol |
|---|---|---|
| OpenAPI Discovery | `/openapi.json` | OpenAPI 3.1 with `x-payment-info` |
| WebMCP Browser Tools | `document.modelContext` | WebMCP client-side tools |
| LLM Context | `/llms.txt` | Plain text overview |
| Extended LLM Context | `/llms-full.txt` | Plain text comprehensive catalog |
| API Catalog | `/.well-known/api-catalog` | RFC 9727 application/linkset+json |
| MCP Server Card | `/.well-known/mcp/server-card.json` | MCP discovery JSON |
| Agent Skills Index | `/.well-known/agent-skills/index.json` | Agent Skills Discovery v0.2.0 |
| ARD Manifest | `/.well-known/ai-catalog.json` | AI Catalog v1.0 |
| Universal Commerce Protocol | `/.well-known/ucp` | UCP profile JSON |
| Agentic Commerce Protocol | `/.well-known/acp.json` | ACP discovery JSON |
| x402 Payment Manifest | `/.well-known/x402` | x402 payment requirements JSON |

---

## Human-in-the-Loop Checkout

For orders placed outside x402 automated settlement, agents can generate human-in-the-loop WhatsApp confirmation links:
1. Agent invokes `sarvadic_order_checkout` or `calculate_order_and_checkout`.
2. A pre-filled WhatsApp deep link is generated to `+91 63552 99199`.
3. Customer confirms delivery address and completes payment via UPI or Net Banking.

---

## Contact & Inquiries

- **Email**: `sarvadicherbal@gmail.com`
- **WhatsApp Support**: `+91 63552 99199`
- **Location**: Vadodara, Gujarat, India
- **Website**: [https://sarvadicherbal.com](https://sarvadicherbal.com)