---
version: "1.0"
authorization_server: "https://yakaai.com"
protected_resource: "https://yakaai.com/api"
flows_supported:
  - agent_verified
  - user_claimed
  - anonymous
identity_types_supported:
  - agent_verified
  - user_claimed
  - anonymous
credential_types_supported:
  - bearer_token
  - jwt_bearer
  - api_key
register_uri: "https://yakaai.com/api/auth/register"
token_endpoint: "https://yakaai.com/api/auth/token"
claim_uri: "https://yakaai.com/api/auth/claim"
revocation_endpoint: "https://yakaai.com/api/auth/revoke"
scopes:
  read:repos: "Search and browse 9,111+ open-source repositories"
  read:docs: "Read full or section-targeted technical documentation"
  read:skills: "Read AI agent rules, prompts, and skills"
  read:specs: "Extract OpenAPI, Swagger, and GraphQL specs"
  read:docker: "Extract Docker Compose and container configs"
  read:apps: "Discover compiled desktop installers and binaries"
  public: "Public unauthenticated read access across all edge endpoints"
---

# 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}`
- **Docker Compose**: `GET https://yakaai.com/api/docker/{owner}/{repo}`
- **Desktop Installers**: `GET https://yakaai.com/api/apps/{owner}/{repo}`

### Option 2: Automated Agent Registration (Agent Verified & User Claimed)
Autonomous agents that require dedicated session tracking, higher concurrency thresholds, or verified identity attestations can register dynamically:
1. Discover authentication endpoints via `/.well-known/oauth-authorization-server` or `/.well-known/oauth-protected-resource`.
2. Send an initial registration handshake to `POST https://yakaai.com/api/auth/register` with agent identity metadata.
3. For user-claimed flows, confirm the claim via `POST https://yakaai.com/api/auth/claim`.
4. Request token from `POST https://yakaai.com/api/auth/token`.
5. Use the returned Bearer token in the `Authorization: Bearer <agent_token>` request header.

---

## 🔑 Supported Identity Types

- **`agent_verified`**: Identity-provider attested verification (WorkOS ID-JAG / agent attestation with no human in the loop).
- **`user_claimed`**: Interactive user-claimed flow with code confirmation.
- **`anonymous`**: Instant public access with zero registration (unlimited read requests within generous IP burst limits).

---

## 🛡️ Supported Credential Types

- **`bearer_token`**: Standard OAuth 2.0 / RFC 6750 Bearer access token.
- **`jwt_bearer`**: RFC 7523 JSON Web Token bearer assertions.
- **`api_key`**: Static API key provided via `Authorization: Bearer <token>` or `x-api-key: <token>`.

---

## 📡 Authentication & Discovery Endpoints

| Protocol Endpoint | URL | Description |
| :--- | :--- | :--- |
| **Agent Registration Spec** | `https://yakaai.com/auth.md` | Auth.md standard specification & instructions |
| **Agent Registration URI** | `https://yakaai.com/api/auth/register` | Automated agent registration endpoint |
| **OAuth Token Endpoint** | `https://yakaai.com/api/auth/token` | Token issuance endpoint |
| **Claim Confirmation** | `https://yakaai.com/api/auth/claim` | User-claimed flow confirmation URL |
| **Token Revocation** | `https://yakaai.com/api/auth/revoke` | Token revocation URL |
| **Protected Resource** | `https://yakaai.com/.well-known/oauth-protected-resource` | RFC 9470 / RFC 9728 Protected Resource metadata |
| **OAuth Discovery** | `https://yakaai.com/.well-known/oauth-authorization-server` | RFC 8414 Authorization Server metadata with `agent_auth` |
| **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/*` | **120 req / min** | **1,200 req / hour** | **5,000 req / day** |
| **Discovery & Search (General)** | `/api/repos`, `/topic/*`, `/resolve/*`, all other `/api/*` | **240 req / min** | **2,400 req / hour** | **15,000 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`, `YakaAI`, `Antigravity`, etc.) are recognized and automatically **exempt** from restrictive rate limits.

---

## ⚙️ Machine-Readable Configuration (agent_auth)

```json
{
  "agent_auth": {
    "version": "1.0",
    "register_uri": "https://yakaai.com/api/auth/register",
    "supported_identity_types": ["agent_verified", "user_claimed", "anonymous"],
    "identity_types_supported": ["agent_verified", "user_claimed", "anonymous"],
    "supported_credential_types": ["bearer_token", "jwt_bearer", "api_key"],
    "credential_types_supported": ["bearer_token", "jwt_bearer", "api_key"],
    "token_endpoint": "https://yakaai.com/api/auth/token",
    "authorization_endpoint": "https://yakaai.com/api/auth/authorize",
    "claim_uri": "https://yakaai.com/api/auth/claim",
    "claim_url": "https://yakaai.com/api/auth/claim",
    "revocation_endpoint": "https://yakaai.com/api/auth/revoke",
    "revocation_uri": "https://yakaai.com/api/auth/revoke",
    "flows_supported": ["agent_verified", "user_claimed", "anonymous"],
    "public_access_supported": true,
    "cors_enabled": true
  }
}
```