# CougarCorner auth.md

You are an agent. This service supports **agentic registration**: discover → register → obtain credentials → call API → handle revocation.

## Overview & Audience

CougarCorner supports autonomous and user-directed AI agents (e.g., ChatGPT, Gemini, Claude, Model Context Protocol clients) acting on behalf of registered BYU sports community members.

Authentication uses personal Bearer tokens provisioned through the agent registration and settings portal.

## Agent Auth Registration Metadata

```json
{
  "resource": "https://cougarcorner.com",
  "authorization_servers": ["https://cougarcorner.com"],
  "scopes_supported": ["predictions:read", "predictions:write", "mcp"],
  "bearer_methods_supported": ["header"],
  "issuer": "https://cougarcorner.com",
  "agent_auth": {
    "skill": "https://cougarcorner.com/auth.md",
    "register_uri": "https://cougarcorner.com/settings",
    "identity_endpoint": "https://cougarcorner.com/settings",
    "claim_endpoint": "https://cougarcorner.com/settings",
    "claim_uri": "https://cougarcorner.com/settings",
    "revocation_uri": "https://cougarcorner.com/settings",
    "identity_types_supported": ["anonymous", "identity_assertion"],
    "anonymous": {
      "credential_types_supported": ["bearer_token"],
      "claim_uri": "https://cougarcorner.com/settings"
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "urn:ietf:params:oauth:token-type:id-jag",
        "verified_email"
      ],
      "credential_types_supported": ["bearer_token"],
      "claim_uri": "https://cougarcorner.com/settings"
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

## Step 1 — Discover

- **Protected Resource**: `https://cougarcorner.com/api`
- **Documentation**: `https://cougarcorner.com/auth.md` and `https://cougarcorner.com/llms.txt`
- **Bearer Methods Supported**: `header` (`Authorization: Bearer cc_agent_...`)

## Step 2 — Supported Methods & Identity Types

- **identity_types_supported**: `["service_auth", "anonymous", "identity_assertion"]`
- **credential_types_supported**: `["bearer_token"]`
- **register_uri**: `https://cougarcorner.com/settings`
- **claim_uri**: `https://cougarcorner.com/settings`
- **revocation_uri**: `https://cougarcorner.com/settings`

## Step 3 — Agent Registration & Provisioning Endpoint

CougarCorner uses human-in-the-loop agent credential provisioning:

1. **User Sign-In**: Member signs into their account at [https://cougarcorner.com/auth/login](https://cougarcorner.com/auth/login).
2. **Registration / Provisioning Endpoint**: Member navigates to [https://cougarcorner.com/settings](https://cougarcorner.com/settings) under **AI Agent API Keys**.
3. **Generate Key**: Click **Generate New Agent Key** to create an API token prefixed with `cc_agent_`.
4. **Credential Use**: The user provides the token to the agent, which includes it in the HTTP `Authorization` header:
   ```http
   Authorization: Bearer cc_agent_<token>
   ```

## Step 4 — Supported Capabilities & Endpoints

| Endpoint | Method | Description | Auth Required |
| :--- | :--- | :--- | :--- |
| `/api/predictions/active` | `GET` | Retrieve active BYU matchup, kickoff date, pick lock status, and prop questions | Optional (enhances response with user picks) |
| `/api/predictions/submit` | `POST` | Submit or update weekly score prediction, margin, and prop answers | **Required** |
| `/api/mcp` | `POST` | Model Context Protocol (MCP) JSON-RPC tool interface | Optional / **Required** for user actions |
| `/api/health` | `GET` | System health & status check | No |

## Step 5 — Error Handling & 401 Challenge

Unauthenticated or invalid requests to protected endpoints return an RFC-compliant 401 challenge:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Agent API key required. See /auth.md for instructions."
Content-Type: application/json

{
  "error": "Unauthorized. Please provide your CougarCorner Agent API Key using the header: Authorization: Bearer <your_key>.",
  "auth_url": "https://cougarcorner.com/auth.md"
}
```

## Step 6 — Revocation & Lifecycle

- **Instant Revocation**: Keys can be immediately revoked at any time via [https://cougarcorner.com/settings](https://cougarcorner.com/settings) (`revocation_uri`).
- **Security**: Tokens are hashed with SHA-256 in the database; plaintext keys cannot be retrieved once created.