# CodingCat.dev auth.md

> Autonomous AI Agent Authentication & Registration Specification for CodingCat.dev APIs and Services.

## 1. Overview & Audience

This document describes authentication and registration procedures for autonomous AI agents, coding assistants, and research tools interacting with CodingCat.dev resources.

- **Audience**: AI Agents, LLM crawlers, automated developer tools, MCP clients.
- **Resource Identifier**: `https://codingcat.dev`
- **Authorization Server**: `https://codingcat.dev`
- **Protected Resource Metadata**: [`https://codingcat.dev/.well-known/oauth-protected-resource`](https://codingcat.dev/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata**: [`https://codingcat.dev/.well-known/oauth-authorization-server`](https://codingcat.dev/.well-known/oauth-authorization-server)
- **OpenID Connect Discovery**: [`https://codingcat.dev/.well-known/openid-configuration`](https://codingcat.dev/.well-known/openid-configuration)

---

## 2. Supported Scopes

| Scope | Description |
| :--- | :--- |
| `read:content` | Read published tutorials, blog posts, podcasts, transcripts, and metadata |
| `search` | Access keyword and semantic search APIs |
| `mcp:tools` | Invoke Streamable HTTP Model Context Protocol (MCP) server tools |
| `agent` | Autonomous agent identity and interactions |

---

## 3. Agent Registration & Provisioning Methods

CodingCat.dev supports programmatic agent registration without human browser interaction.

### Method A: Anonymous Instant Bearer Token (Recommended for Reading & Search)

Agents requiring unauthenticated read access can claim an anonymous bearer token immediately:

- **Endpoint**: `POST https://codingcat.dev/agent/claim`
- **Identity Type**: `anonymous`
- **Credential Type**: `bearer`
- **Request**:
  ```http
  POST https://codingcat.dev/agent/claim HTTP/1.1
  Content-Type: application/json

  {
    "identity_type": "anonymous",
    "requested_scopes": ["read:content", "search", "mcp:tools"]
  }
  ```
- **Response**:
  ```json
  {
    "access_token": "cat_anon_eyJ...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "read:content search mcp:tools"
  }
  ```

### Method B: Identity Assertion (ID-JAG & Verified Email)

For agents with verified identities or software statements:

- **Endpoint**: `POST https://codingcat.dev/agent/auth`
- **Identity Types Supported**: `identity_assertion`, `anonymous`
- **Assertion Types Supported**:
  - `urn:ietf:params:oauth:token-type:id-jag` (JSON Web Token Agent Grant)
  - `verified_email`
- **Credential Types Supported**: `bearer`
- **Request**:
  ```http
  POST https://codingcat.dev/agent/auth HTTP/1.1
  Content-Type: application/json

  {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:id-jag",
    "subject_token": "<jwt-assertion>",
    "scope": "read:content search mcp:tools agent"
  }
  ```

---

## 4. Using Credentials

When calling protected API or MCP endpoints, include the access token in the `Authorization` request header:

```http
GET https://codingcat.dev/api/search?q=astro HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
```

```http
POST https://codingcat.dev/api/mcp HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

---

## 5. Public Unauthenticated Endpoints

Public search (`/api/search`), public MCP tool execution (`/api/mcp`), and Markdown content negotiation (`Accept: text/markdown`) do not require authentication for passive research or search bots.