# LeaseGuru.ai auth.md — Agent Authentication & Registration Discovery

LeaseGuru.ai is a US car-lease comparison marketplace. This `auth.md` document defines how autonomous AI agents, MCP clients, shopping assistants, and automated tools authenticate and interact with LeaseGuru.ai resources.

## Agent Audience

This specification applies to:
- Autonomous AI shopping and research agents querying live car lease deals, brand/model catalog rollups, and LeaseGuru 1–100 deal scores.
- Model Context Protocol (MCP) and Agent-to-Agent (A2A) clients connecting via `https://leaseguru.ai/.well-known/mcp/server-card.json` or `https://leaseguru.ai/.well-known/agent-card.json`.
- Automated discovery scanners reading `https://leaseguru.ai/.well-known/api-catalog`.

## Public Read Access (No Credentials Required)

Browsing and reading LeaseGuru.ai marketplace data is free and requires no user account or API key for standard read operations:
- **Live deals API:** `GET https://leaseguru.ai/api/deals-page`
- **Brand & model catalog API:** `GET https://leaseguru.ai/api/search-catalog`
- **VIN decoder API:** `GET https://leaseguru.ai/api/vin-decode?vin={VIN}`
- **LLM reference summary:** `GET https://leaseguru.ai/llms.txt` (or `GET https://leaseguru.ai/` with `Accept: text/markdown`)
- **OpenAPI 3.1 specification:** `GET https://leaseguru.ai/openapi.json`

## OAuth Discovery & Anonymous Agent Registration

For agents that require a registered session token or standardized OAuth 2.0 / Auth.md onboarding, LeaseGuru.ai publishes OAuth Protected Resource Metadata and OAuth Authorization Server Metadata supporting the `anonymous` agent identity profile:

- **Protected Resource Metadata (RFC 9728):** `https://leaseguru.ai/.well-known/oauth-protected-resource`
- **Authorization Server Metadata (RFC 8414):** `https://leaseguru.ai/.well-known/oauth-authorization-server`
- **Agent Registration Endpoint (`register_uri`):** `POST https://leaseguru.ai/api/agent/register`
- **Anonymous Credential Claim Endpoint (`claim_uri`):** `POST https://leaseguru.ai/api/agent/claim`
- **Credential Revocation Endpoint (`revocation_uri`):** `POST https://leaseguru.ai/api/agent/revoke`

### Supported Authentication Methods

1. **Anonymous Bearer Credentials (`identity_types_supported: ["anonymous"]`):**
   - Credential type: `bearer`
   - Scopes supported: `deals:read`, `catalog:read`, `vin:read`
   - Registration flow: Submit an agent registration payload to `POST https://leaseguru.ai/api/agent/register` and claim the short-lived bearer credential via `POST https://leaseguru.ai/api/agent/claim`.
2. **Direct Unauthenticated Read Access:**
   - Public `GET` endpoints accept unauthenticated requests directly over HTTPS.

### Credential Use

Pass issued bearer credentials in the HTTP `Authorization` request header:

```http
GET /api/deals-page?make=BMW&maxPayment=600 HTTP/1.1
Host: leaseguru.ai
Authorization: Bearer <agent_access_token>
Accept: application/json
```

> **Note for Passive Scanners:** Do not probe `POST` registration or lead submission endpoints during passive scans. Public discovery documents (`/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, and `/auth.md`) are the authoritative source of truth.