# Auth.md

Welcome, AI agent. This document outlines how you can programmatically register, discover, and authenticate on behalf of a user against TunePrime (`https://tuneprime.app`) without requiring a human-driven web form or manual API key generation.

---

## 1. Discover Endpoints

This service implements standard OAuth 2.0 Protected Resource Metadata (RFC 9728) and Authorization Server Metadata (RFC 8414) for agent discovery:

- **Protected Resource Metadata**: `https://tuneprime.app/.well-known/oauth-protected-resource`
- **Authorization Server Metadata**: `https://tuneprime.app/.well-known/oauth-authorization-server`
- **Agent Skill / Instructions**: `https://tuneprime.app/auth.md`
- **Agent Registration URI**: `https://tuneprime.app/agent/identity`
- **Token Endpoint**: `https://tuneprime.app/oauth2/token`

---

## 2. Standalone Agent Registration Flow

Follow this self-contained, 3-step registration process to register your agent and obtain credentials.

### Step 1: Register Agent Identity

Submit a registration request to the `register_uri`:

```http
POST /agent/identity HTTP/1.1
Host: tuneprime.app
Content-Type: application/json

{
  "type": "anonymous"
}
```

Response:
```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "identity_type": "anonymous",
  "register_uri": "https://tuneprime.app/agent/identity",
  "token_endpoint": "https://tuneprime.app/oauth2/token",
  "identity_assertion": "tuneprime_open_access_assertion"
}
```

### Step 2: Exchange Assertion for Access Token

Exchange the `identity_assertion` at the token endpoint:

```http
POST /oauth2/token HTTP/1.1
Host: tuneprime.app
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=tuneprime_open_access_assertion
```

Response:
```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "tuneprime_open_access_token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "radio:read tv:read podcasts:read"
}
```

### Step 3: Access Protected APIs

Call protected endpoints using the standard Bearer header:

```http
GET /geo HTTP/1.1
Host: tuneprime.app
Authorization: Bearer tuneprime_open_access_token
```

Response:
```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "country": "RO",
  "timezone": "Europe/Bucharest"
}
```

---

## 3. Alternative Integration Flows

### Option A: Direct Public Access (Zero-Auth / Recommended)
TunePrime is fundamentally open. All core streaming discovery, radio catalog, podcast RSS feeds, and 4K TV teaser previews are accessible with zero authentication:
- **Agent Registration Required**: No registration required for public APIs.
- **Header**: Simply provide a descriptive `User-Agent: MyAgent/1.0 (+https://example.com/bot)`.
- **Public Endpoints**:
  - `GET https://tuneprime.app/geo` (Geolocation detection)
  - `GET https://tuneprime.app/openapi.json` (OpenAPI 3.1 specification)
  - `GET https://tuneprime.app/llms.txt` & `https://tuneprime.app/llms-full.txt` (Structured context)
  - `GET https://radio.tuneprime.app/heartbeat-stats` (Live telemetry)

### Option B: Agent Verified Flow (ID-JAG)
If your agent environment is backed by a trusted identity provider (WorkOS, OpenAI, Anthropic, Cursor) minting ID-JAG identity assertions:
1. Mint an **Identity Assertion JWT Authorization Grant (ID-JAG)** for the user.
2. `POST` the assertion to `https://tuneprime.app/agent/identity`.
3. Exchange the returned assertion at `https://tuneprime.app/oauth2/token` for a user-scoped token.

---

## 4. Scope Inventory

When requesting access tokens, limit scopes to the minimum necessary:
* `radio:read` — Read-only access to global radio directory, stream URLs, and metadata.
* `tv:read` — Read-only access to TV channel guide and 4K stream metadata.
* `podcasts:read` — Access to podcast catalog and RSS feed parser proxy.

---

## 5. Additional Resources & Policies
* **Terms of Service:** `https://tuneprime.app/`
* **Privacy Policy:** `https://tuneprime.app/` (Zero personal data collected, zero tracking cookies, zero ads).
* **Caching:** Cache responses in accordance with HTTP `Cache-Control` headers.
* **Support Contact:** `popescumirce@gmail.com`