# Auth.md

> DJ Discover — Official Authentication and Agent Registration Policy

## Overview

This document specifies the authentication, authorization, and agent registration discovery metadata for AI agents, LLMs, and autonomous tools interacting with the DJ Discover platform (https://www.djdiscover.com).

- **Service Name:** DJ Discover
- **API Base URL:** `https://api.djdiscover.com`
- **Web Origin:** `https://www.djdiscover.com`
- **Protected Resource Identifier:** `https://api.djdiscover.com`
- **Authorization Server:** `https://api.djdiscover.com/auth`
- **OAuth Protected Resource Metadata:** `https://www.djdiscover.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata:** `https://www.djdiscover.com/.well-known/oauth-authorization-server`

---

## Public Agent Access (Zero-Auth / Open Discovery)

AI agents do **not** require registration or API keys to read public music profiles, DJ press kits, public rankings, and session metadata.

### Public Read Endpoints
- **DJ Technical Profile & Press Kit (Markdown / JSON):**  
  `GET https://www.djdiscover.com/api/agent/dj/{username}`  
  *(Send header `Accept: text/markdown` for pure markdown representation)*
- **Public Press Kits Directory:**  
  `GET https://api.djdiscover.com/stats/public-press-kits`
- **Official DJ Rankings:**  
  `GET https://api.djdiscover.com/stats/all-djs-with-ratings`
- **Search DJs and Music Styles:**  
  `GET https://api.djdiscover.com/djs/search?q={query}`
- **LLM Knowledge Base:**  
  `GET https://www.djdiscover.com/llms.txt`

---

## Agent Registration & OAuth 2.0 Discovery

For agents performing user-delegated actions or authenticated calls:

- **Registration URI:** `https://www.djdiscover.com/auth.md`
- **Token Endpoint:** `https://api.djdiscover.com/auth/login`
- **Supported Identity Types:** `agent`, `bot`, `developer`
- **Supported Credential Types:** `bearer_token`, `api_key`
- **Grant Types:** `password`, `refresh_token`
- **Supported Scopes:**
  - `read:public` — Public session, DJ, and ranking metadata
  - `read:djs` — Detailed DJ artist profiles and style categories
  - `read:presskits` — Professional press kits, media embeds, and booking contacts
  - `user:profile` — User profile management

---

## Usage Guidelines for Agents

1. **User-Agent:** Agents must identify themselves with an informative `User-Agent` string (e.g., `MyAgent/1.0 (+https://example.com/bot)`).
2. **Rate Limits:** Up to 60 requests per minute for unauthenticated queries.
3. **Contact:** For high-throughput partnerships or API limits, contact `info@djdiscover.com`.