# Agent Registration & Authentication (auth.md)

> **Platform**: YakaAI Documentation Hub  
> **Specification**: Agent Auth RFC / WorkOS auth.md Standard  
> **Auth Model**: Zero-Auth Public Edge Access & Dynamic Agent Registration  
> **Base URL**: `https://yakaai.com/api`  
> **CORS**: `Access-Control-Allow-Origin: *`  

---

## 🤖 Agent Registration Instructions

AI agents, autonomous coding assistants (Claude, Cursor, Copilot, Gemini, DeepSeek), and LLM pipelines can connect to YakaAI using two methods:

### Option 1: Zero-Configuration Anonymous Access (Default)
YakaAI allows immediate unauthenticated requests for all public endpoints. No upfront registration or API keys are required.
- **Cheatsheet Docs**: `GET https://yakaai.com/api/cheat/{owner}/{repo}`
- **Targeted Section Docs**: `GET https://yakaai.com/api/cheat/{owner}/{repo}?section={topic}`
- **Agent Skills Scanner**: `GET https://yakaai.com/api/skills/{owner}/{repo}`
- **API Specs**: `GET https://yakaai.com/api/spec/{owner}/{repo}`

### Option 2: Automated Agent Registration
Autonomous agents that require dedicated session tracking, higher concurrency thresholds, or webhook notifications can register dynamically:
1. Discover authentication endpoints via `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration`.
2. Send an initial registration handshake to `https://yakaai.com/api/auth/register` with agent identity metadata.
3. Use the returned Bearer token in the `Authorization: Bearer <agent_token>` request header.

---

## 🔑 Supported Identity Types

- **`anonymous`**: Instant public access with zero registration (unlimited read requests within generous IP burst limits).
- **`agent_token`**: Ephemeral agent JWT tokens for high-throughput autonomous swarms.
- **`bearer`**: Standard OAuth 2.0 / RFC 6750 Bearer authentication.

---

## 🛡️ Supported Credential Types

- **`none`**: Public unauthenticated client access.
- **`api_key`**: Static API key provided via `Authorization: Bearer <token>` or `x-api-key: <token>`.
- **`jwt_bearer`**: RFC 7523 JSON Web Token bearer assertions.

---

## 📡 Authentication & Discovery Endpoints

| Protocol Endpoint | URL | Description |
| :--- | :--- | :--- |
| **Agent Registration** | `https://yakaai.com/auth.md` | Registration guide & identity protocol |
| **OAuth Authorization** | `https://yakaai.com/api/auth/authorize` | Authorization grant endpoint |
| **OAuth Token** | `https://yakaai.com/api/auth/token` | Token issuance endpoint |
| **Token Revocation** | `https://yakaai.com/api/auth/revoke` | Token invalidation endpoint |
| **Protected Resource** | `https://yakaai.com/.well-known/oauth-protected-resource` | RFC 9728 Protected Resource metadata |
| **OAuth Discovery** | `https://yakaai.com/.well-known/oauth-authorization-server` | RFC 8414 Authorization Server metadata |
| **API Catalog** | `https://yakaai.com/.well-known/api-catalog` | RFC 9727 API Catalog |
| **MCP Server Card** | `https://yakaai.com/.well-known/mcp/server-card.json` | SEP-1649 MCP Server Card |

---

## 🛡️ Freemium Public Quotas & Multi-Window Rate Limiting

To guarantee extreme edge availability, prevent quota exhaustion, and strictly respect Cloudflare Free Tier constraints (100k requests/day, 5M D1 reads/day), all incoming traffic is governed by multi-window edge rate limiting:

| Endpoint Tier | Routes | Per Minute Limit | Per Hour Limit | Per Day (Daily Quota) |
| :--- | :--- | :--- | :--- | :--- |
| **Documentation & Skills (Heavy)** | `/api/cheat/*`, `/api/skills/*`, `/api/spec/*`, `/doc/*` | **30 req / min** | **300 req / hour** | **500 req / day** *(No skill expansion)* |
| **Discovery & Search (General)** | `/api/repos`, `/topic/*`, all other `/api/*` | **60 req / min** | **600 req / hour** | **1,500 req / day** |

### 🤖 Automatic Exemption for Verified AI Bots
Major AI search and retrieval crawlers (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `Googlebot`, `Applebot`, `Bingbot`, `Cohere-AI`, `OAI-SearchBot`, `CCBot`, etc.) are recognized and automatically **exempt** from restrictive rate limits.

### 📊 Standardized RateLimit Response Headers
Every API response provides live quota consumption telemetry:
- `X-RateLimit-Limit-Minute`: Limit per 60 seconds
- `X-RateLimit-Remaining-Minute`: Remaining tokens in current minute
- `X-RateLimit-Limit-Hour`: Limit per 3,600 seconds
- `X-RateLimit-Remaining-Hour`: Remaining tokens in current hour
- `X-RateLimit-Limit-Day`: Limit per 86,400 seconds
- `X-RateLimit-Remaining-Day`: Remaining tokens in current 24-hour window
- `X-RateLimit-Reset`: Unix epoch timestamp when current window resets
- `RateLimit-Policy`: RFC draft format e.g. `30;w=60, 300;w=3600, 1000;w=86400`
- `Retry-After`: Seconds to wait before retrying if HTTP 429 is received

---

## ⚙️ Machine-Readable Configuration (agent_auth)

```json
{
  "agent_auth": {
    "version": "1.0.0",
    "register_uri": "https://yakaai.com/auth.md",
    "supported_identity_types": ["anonymous", "agent_token", "bearer"],
    "supported_credential_types": ["none", "api_key", "jwt_bearer"],
    "token_endpoint": "https://yakaai.com/api/auth/token",
    "authorization_endpoint": "https://yakaai.com/api/auth/authorize",
    "revocation_endpoint": "https://yakaai.com/api/auth/revoke",
    "public_access_supported": true,
    "cors_enabled": true
  }
}
```