# auth.md: Agent Registration & API Authentication Guide

Welcome to the automated authentication and registration guide for AI agents interacting with **Aravind Venugopal's** portfolio APIs.

---

## 1. Overview & Audience

This document describes how autonomous agents, crawlers, and AI systems can programmatically authenticate, obtain session credentials, and call protected APIs on `https://aravind.me`.

- **Protected Resource**: `https://aravind.me`
- **Authorization Server**: `https://aravind.me`
- **Discovery Endpoints**:
  - OAuth Protected Resource Metadata: `https://aravind.me/.well-known/oauth-protected-resource`
  - OAuth Authorization Server: `https://aravind.me/.well-known/oauth-authorization-server`
  - OpenID Configuration: `https://aravind.me/.well-known/openid-configuration`
  - API Catalog (RFC 9727): `https://aravind.me/.well-known/api-catalog`
  - ARD Manifest: `https://aravind.me/.well-known/ai-catalog.json`

---

## 2. Authentication Methods

### Method A: Cryptographic Session Handshake (Zero-Registration / Default)
For real-time concierge chat, speech-to-text, and voice synthesis, AI agents can immediately acquire a 30-minute HMAC session token without manual pre-registration.

1. **Request Session Token**:
   ```http
   GET /api/health HTTP/1.1
   Host: aravind.me
   Origin: https://aravind.me
   ```

2. **Receive Token in JSON**:
   ```json
   {
     "ok": true,
     "groq": true,
     "sarvam": true,
     "chat": true,
     "stt": true,
     "tts": true,
     "sessionToken": "4fa9c...:1724785200000:a1b2c3d4..."
   }
   ```

3. **Call Protected Routes with Token Header**:
   Attach the token via the `x-portfolio-session` header:
   ```http
   POST /api/chat HTTP/1.1
   Host: aravind.me
   Content-Type: application/json
   x-portfolio-session: <YOUR_SESSION_TOKEN>

   {
     "messages": [
       {"role": "user", "content": "What is Aravind's leadership experience at Target?"}
     ]
   }
   ```

### Method B: Automated Agent Registration (OAuth 2.0 / Agent Auth)
- **Registration URI**: `https://aravind.me/oauth/register`
- **Supported Identity Types**: `anonymous`, `identity_assertion`
- **Bearer Methods Supported**: `header` (`Authorization: Bearer <TOKEN>`)

---

## 3. Scopes & Permissions

| Scope | Description | Default Access |
|---|---|---|
| `read:profile` | Query canonical profile, resume, and structured portfolio data | Public / Anonymous |
| `chat:concierge` | Interactive SSE stream with Groq `openai/gpt-oss-120b` | Session Token Required |
| `voice:stt` | Transcribe audio via Groq Whisper Turbo | Session Token Required |
| `voice:tts` | Synthesize neural speech via Sarvam Bulbul | Session Token Required |

---

## 4. Rate Limits & Guardrails

- **Sliding-Window IP Rate Limits**:
  - `POST /api/chat`: 25 requests / minute
  - `POST /api/stt`: 20 requests / minute
  - `POST /api/tts`: 20 requests / minute
  - `POST /api/chat-summary`: 20 requests / minute
- **Security Guardrails**:
  - Direct proxy endpoints require session tokens and allowlisted origins.
  - Queries are topic-gated to Aravind's verified career history, systems architecture, metrics, and products.
  - Cross-site POST requests without valid session signatures return `401 Unauthorized` / `403 Forbidden`.

---

## 5. Contact & Support

For developer inquiries or extended API quotas:
- **Email**: `hello@aravind.me`
- **Canonical Site**: `https://aravind.me`
- **Agent Specification**: `https://aravind.me/agent.md`