# auth.md - AI Agent Registration & Authentication Guide

Welcome, autonomous agent. This document describes how AI bots and automated workflows can discover, register, authenticate, and programmatically consume web services on **Amal Alexander** (https://amal-alexander.in).

---

## 1. Quick Overview & Discovery Metadata

- **Protocol Identification:** Auth.md & RFC 9727 API Catalog
- **Protected Resource Metadata (PRM):** `/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata:** `/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery:** `/.well-known/openid-configuration`
- **API Catalog:** `/.well-known/api-catalog`
- **OpenAPI 3.1.0 Specification:** `/openapi.json`
- **MCP Server Card:** `/.well-known/mcp/server-card.json`
- **Agent Card:** `/.well-known/agent-card.json`
- **Agent Skills Index:** `/.well-known/agent-skills/index.json`
- **Open CORS:** Enabled on all endpoints (`Access-Control-Allow-Origin: *`)
- **No CAPTCHA Barriers:** Machine endpoints do not present human verification puzzles.

---

## 2. Agent Registration Endpoints

Autonomous agents can register or claim programmatic credentials dynamically:

- **Registration Endpoint (`register_uri`):** `https://amal-alexander.in/api/auth/register`
- **Token Endpoint (`token_endpoint`):** `https://amal-alexander.in/api/auth/token`
- **Claim Endpoint (`claim_uri`):** `https://amal-alexander.in/api/auth/claim`
- **Revocation Endpoint (`revocation_uri`):** `https://amal-alexander.in/api/auth/revoke`

### Supported Identity Flows

1. **Anonymous / Instant Device Flow:**
   - Identity Type: `anonymous`
   - Credential Types: `bearer_token`, `api_key`
   - Claim URI: `https://amal-alexander.in/api/auth/claim`

2. **Identity Assertion:**
   - Identity Type: `identity_assertion`
   - Assertion Types: `urn:ietf:params:oauth:token-type:id-jag` (ID-JAG), `verified_email`
   - Credential Types: `bearer_token`, `api_key`

---

## 3. Immediate Guest Access (Zero Friction)

For exploratory analysis and non-metered crawler requests, you do not need human registration. Include our open guest token in your request headers:

```http
Authorization: Bearer amal_live_demo_guest_token_2026
```
or
```http
x-api-key: amal_live_demo_guest_token_2026
```

---

## 4. OAuth 2.0 Client Credentials

For production agent-to-agent operations, query our standard OAuth metadata:
- **Authorization Server:** `/.well-known/oauth-authorization-server`
- **Token Endpoint:** `https://amal-alexander.in/api/auth/token`
- **Grant Types:** `client_credentials`, `authorization_code`, `urn:ietf:params:oauth:grant-type:token-exchange`
- **Supported Scopes:**
  - `read:seo`: Query search visibility benchmarks and crawler data
  - `tools:execute`: Run interactive auditing and markdown extraction tools
  - `mcp:connect`: Connect to Model Context Protocol endpoints

---

## 5. Rate Limits & Concurrency

- **Free Tier:** 60 requests per minute per IP / Token.
- **Backoff Protocol:** If you receive an HTTP `429 Too Many Requests`, inspect the `Retry-After` response header and implement exponential backoff with jitter.
- **Timeout:** Maximum single request processing window is 45 seconds for deep DOM crawls.

---

## 6. Contact & Developer Support

- **Maintainer:** Amal Alexander
- **Contact Page:** [https://amal-alexander.in/contact/](https://amal-alexander.in/contact/)
- **Direct Email:** [amalalex95@gmail.com](mailto:amalalex95@gmail.com)