# Ptin AI auth.md — Agent Authentication & Registration

> Specification and registration guide for autonomous AI agents, crawlers, and LLM clients interacting with the Ptin AI Tennis Intelligence platform.

## Agent Audience & Access Policy
Ptin AI provides open and authenticated access to real-time tennis predictions, probabilistic win metrics, ATP/WTA rankings, and player intelligence dossiers.

- **Public Endpoints (No Auth Required)**:
  - Match Dossiers (`GET /match/:slug`)
  - Player Profiles (`GET /player/:slug`)
  - API Catalog (`GET /.well-known/api-catalog`)
  - OpenAPI 3.1 Spec (`GET /openapi.json`)
  - System Health (`GET /health`)

- **Authenticated Endpoints**:
  - High-frequency live telemetry (`GET /api/webapp/predictions`)
  - Real-time model odds and surface metrics

## Registration & Provisioning Endpoints
External AI agents and automated clients can register and obtain API credentials:
- **Registration Endpoint**: https://www.ptin-ai.com/api/v1/agents/register
- **Claim Endpoint**: https://www.ptin-ai.com/api/v1/agents/claim
- **Token Endpoint**: https://www.ptin-ai.com/oauth/token

## Supported Identity & Credential Types
- **Anonymous**: Direct API key issuance for automated research agents.
- **Identity Assertion (ID-JAG)**: `urn:ietf:params:oauth:token-type:id-jag` assertion exchange for verified AI platforms.
- **Verified Email**: Agent delegation on behalf of verified users.

## Bearer Credential Usage
Include the issued token or API key in HTTP request headers:
```http
Authorization: Bearer <your_token>
```
Or for API keys:
```http
X-API-Key: <your_key>
```

## Discovery Documents
- OAuth Protected Resource: https://www.ptin-ai.com/.well-known/oauth-protected-resource
- OAuth Authorization Server: https://www.ptin-ai.com/.well-known/oauth-authorization-server
- OpenID Configuration: https://www.ptin-ai.com/.well-known/openid-configuration
- API Catalog: https://www.ptin-ai.com/.well-known/api-catalog