# CatchAI Text auth.md

Welcome to the automated agent registration and authentication specification for CatchAI Text. This document defines machine-to-machine authentication, dynamic client registration, and token exchange protocols for autonomous agents, IDE plugins, research bots, and automated integrity evaluation systems.

## 1. Agent Audience

This service is designed for:
- Autonomous AI evaluation agents and LLM tool-calling runners.
- Academic integrity verification pipelines and learning management systems (LMS).
- Desktop, CLI, and IDE extensions performing offline or cloud-assisted stylometric checks.
- Automated document batch analyzers.

## 2. Discovery Endpoints

CatchAI Text advertises standard OAuth 2.0 and agent discovery manifests:

- **OAuth Protected Resource Metadata (PRM)**: `/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata**: `/.well-known/oauth-authorization-server`
- **OpenID Discovery**: `/.well-known/openid-configuration`
- **RFC 9727 API Catalog**: `/.well-known/api-catalog`
- **OpenAPI 3.1 Specification**: `/openapi.json`
- **LLM Manifest**: `/llms.txt`

## 3. Supported Authentication & Registration Methods

CatchAI Text supports four discovery-backed registration and assertion methods:

### Method A: Anonymous & Ephemeral Provisioning (Zero-Friction)
Autonomous agents requiring instant text verification without permanent credentials may request ephemeral execution tokens.
- **Identity Type**: `anonymous`
- **Credential Types**: `ephemeral_bearer_token`, `client_assertion`
- **Claim URI**: `https://catchaitext.com/api/agent/anonymous-claim`
- **Headers**:
  ```http
  POST /api/agent/anonymous-claim HTTP/1.1
  Host: catchaitext.com
  Content-Type: application/json

  {
    "client_name": "MyAutonomousAgent/1.0",
    "requested_scopes": ["detect:read"]
  }
  ```

### Method B: ID-JAG Identity Assertion (Cryptographic Exchange)
Enterprise agents presenting signed Identity-JAG assertions (`urn:ietf:params:oauth:token-type:id-jag`).
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types**: `bearer_token`, `api_key`
- **Registration URI**: `https://catchaitext.com/api/agent/register`
- **Claim URI**: `https://catchaitext.com/api/agent/claim`
- **Revocation URI**: `https://catchaitext.com/api/agent/revoke`
- **Events Supported**: `revocation`

### Method C: Verified Email Assertion
Educational institutions and researchers verifying agent identity via organizational email claims.
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `verified_email`
- **Credential Types**: `bearer_token`, `api_key`
- **Registration URI**: `https://catchaitext.com/api/agent/register`
- **Claim URI**: `https://catchaitext.com/api/agent/claim`

### Method D: Dynamic Client Registration (RFC 7591)
- **Registration Endpoint**: `https://catchaitext.com/oauth/register`
- **Token Endpoint**: `https://catchaitext.com/oauth/token`
- **Grant Types**: `client_credentials`, `urn:ietf:params:oauth:grant-type:token-exchange`
- **Token Auth Methods**: `client_secret_basic`, `client_secret_post`, `private_key_jwt`, `none`

## 4. Credential Usage & Request Execution

Once issued, credentials MUST be transmitted via the standard HTTP `Authorization` header:

```http
POST /api/detect HTTP/1.1
Host: catchaitext.com
Authorization: Bearer <issued_agent_token>
Content-Type: application/json

{
  "text": "Sample text for stylometric evaluation..."
}
```

- **Bearer Methods Supported**: `header`
- **Supported Scopes**:
  - `detect:read`: Read and execute stylometric detection algorithms.
  - `detect:write`: Submit human-in-the-loop retraining feedback.
  - `weights:read`: Inspect active logistic model weights and thresholds.
  - `offline:access`: Request persistent refresh capabilities.

## 5. Security & Rate Governance

- All tokens are bound to client subnets and device identities to prevent credential theft.
- Rate limits: 300 requests per 15-minute window for standard tokens; unauthenticated public requests adhere to IP-based rate limiting.
- Public discovery endpoints are idempotent and safe for passive scanners.