# auth.md

You are an agent. This service supports **anonymous agentic registration**: discover → register → use. Follow the steps in order.

Examples use the host `https://idolinfohub.com`. The `agent_auth` block in the Authorization Server metadata is the authoritative source; this document is the prose companion.

## Public access (no credentials required)

All content is freely readable without any credential. Agents may access the following endpoints directly without registering:

| Endpoint | Description |
|----------|-------------|
| `POST /mcp` | MCP Streamable HTTP (JSON-RPC 2.0, protocol `2025-03-26`) — lists and reads events, performers, hosts, venues as content resources. Discovery: `/.well-known/mcp/server-card.json` |
| `/.well-known/agent-skills/index.json` | Agent-skills discovery index |
| `/.well-known/agent-skills/idol-info-hub.md` | Agent skill document |
| `/llms.txt` | LLM-readable site summary |
| `/.well-known/api-catalog` | RFC 9264 API linkset |
| `/sitemap.xml` | Full site map |
| `Accept: text/markdown` on any route | Returns pre-built Markdown companion |

Registration is optional. It issues a scoped `api_key` credential for `mcp:resources` access. Public (unauthenticated) access remains unrestricted.

---

## Step 1 — Discover

Discovery is two hops.

### 1a. Fetch the Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
```

Response:

```json
{
  "resource": "https://idolinfohub.com",
  "resource_name": "Idol Info Hub",
  "resource_documentation": "https://idolinfohub.com/auth.md",
  "authorization_servers": ["https://idolinfohub.com"],
  "scopes_supported": ["mcp:resources"],
  "bearer_methods_supported": ["header"]
}
```

### 1b. Fetch the Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
```

Read the `agent_auth` block:

```json
{
  "agent_auth": {
    "skill": "https://idolinfohub.com/auth.md",
    "register_uri": "https://idolinfohub.com/agent/auth",
    "claim_uri": "https://idolinfohub.com/agent/auth/claim",
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": ["api_key"]
    }
  }
}
```

## Step 2 — Register (anonymous)

This service accepts **anonymous** registration only. No user identity is required.

```http
POST /agent/auth
Content-Type: application/json

{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}
```

Successful response:

```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "credential_type": "api_key",
  "credential": "sk_...",
  "credential_expires": null,
  "scopes": ["mcp:resources"],
  "claim_url": "https://idolinfohub.com/agent/auth/claim",
  "claim_token": "clm_..."
}
```

Store the `credential`. The optional claim ceremony at `claim_uri` lets a user take ownership of the registration.

## Step 3 — Use the credential

Present as a bearer token:

```http
POST /mcp
Authorization: Bearer <credential>
Content-Type: application/json
```

The `mcp:resources` scope grants read access to all MCP resources. On a `401`, drop the credential and restart at Step 1.