# Mandi Rate Agent Authentication Guide (`auth.md`)

Welcome to the Mandi Rate platform for AI Agents. This document defines the protocol for AI agents to discover, register, and authenticate with the Mandi Rate API.

## 1. Overview
- **Service Name**: Mandi Rate (Pakistan Vegetable Market Rates & Ordering)
- **Base URL**: `https://mandirate.com`
- **Supported Auth Protocols**: OAuth 2.0 (RFC 6749), OpenID Connect (OIDC), Bearer Token

## 2. Public vs. Protected Endpoints
- **Public Endpoints (No Auth Required)**:
  - `GET /api/rates` — Read daily mandi prices and vegetable catalog.
  - `GET /api/health` — Check system and sync health status.
  - `GET /.well-known/ai-catalog.json` — Agentic Resource Discovery manifest.
  - `GET /.well-known/mcp/server-card.json` — Model Context Protocol server configuration.
- **Protected Endpoints (Agent Auth Required)**:
  - `POST /api/orders` — Programmatically submit vegetable delivery orders on behalf of users.
  - `GET /api/orders/:id` — Retrieve status and history of agent-placed orders.

## 3. OAuth & OIDC Discovery Endpoints
- **Authorization Server**: `/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `/.well-known/openid-configuration`
- **Protected Resource Metadata**: `/.well-known/oauth-protected-resource`

## 4. Agent Registration Flow (`agent_auth`)
Autonomous agents may obtain an API key or dynamic client credential by registering with the agent registration endpoint:
- **Registration Endpoint**: `https://mandirate.com/api/agent/register`
- **Supported Identity Types**:
  - `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
  - `agent-key`
- **Supported Scopes**:
  - `rates:read` — Read real-time vegetable market rates.
  - `orders:create` — Submit orders for home or restaurant delivery.
  - `orders:read` — Monitor order fulfillment status.

## 5. Sample Authorization Header
```http
Authorization: Bearer <agent_access_token>
```