# auth.md

> Autonomous Agent Authentication, Verification & Registration Protocol for TradingMaster.app (https://tradingmaster.app)

## 1. Overview & Agent Identity

TradingMaster.app provides automated quantitative analytics, algorithmic backtesting data, position sizing calculations, and market microstructure models. AI Agents, LLM tools, and automated systems can register as authenticated callers to execute tools and query real-time market data.

- **Protected Resource Metadata**: [https://tradingmaster.app/.well-known/oauth-protected-resource](https://tradingmaster.app/.well-known/oauth-protected-resource)
- **OAuth Authorization Server**: [https://tradingmaster.app/.well-known/oauth-authorization-server](https://tradingmaster.app/.well-known/oauth-authorization-server)
- **Model Context Protocol (MCP)**: [https://tradingmaster.app/.well-known/mcp.json](https://tradingmaster.app/.well-known/mcp.json)
- **Agent Skills Discovery**: [https://tradingmaster.app/.well-known/agent-skills/index.json](https://tradingmaster.app/.well-known/agent-skills/index.json)

---

## 2. Agent Registration Workflow

### Supported Identity Types
- `identity_assertion`: Verified ID-JAG or verified email assertion tokens.
- `anonymous`: Ephemeral trial registration for unauthenticated agents with organization-scoped rate limits.
- `service_auth`: Service account registration with email claim ceremony.

### Step 1: Dynamic Agent Registration
Agents register by submitting their identity metadata to the registration endpoint:

```http
POST https://tradingmaster.app/api/auth/register-agent HTTP/1.1
Host: tradingmaster.app
Content-Type: application/json

{
  "client_name": "MyQuantitativeAgent",
  "client_uri": "https://agent.example.com",
  "identity_type": "autonomous_agent",
  "grant_types": ["client_credentials"],
  "response_types": ["token"],
  "scope": "strategies:read calculators:execute"
}
```

### Step 2: Receive Client Credentials
Upon successful registration, TradingMaster.app returns credentials:

```json
{
  "client_id": "tm_agent_98a72b14c3e",
  "client_secret": "tm_sec_8849bf29a01c74d8e3",
  "client_id_issued_at": 1771860000,
  "client_secret_expires_at": 0,
  "token_endpoint": "https://tradingmaster.app/api/auth/token"
}
```

### Step 3: Obtain Access Token
Request an access token via standard OAuth 2.0 `client_credentials`:

```http
POST https://tradingmaster.app/api/auth/token HTTP/1.1
Host: tradingmaster.app
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=tm_agent_98a72b14c3e&client_secret=tm_sec_8849bf29a01c74d8e3&scope=strategies:read%20calculators:execute
```

---

## 3. Supported Scopes & Permissions

| Scope | Description | Access Level |
|---|---|---|
| `strategies:read` | Query quantitative blueprints, backtest metrics, and mathematical formulas | Read-Only |
| `calculators:execute` | Run position sizing, Kelly criterion, and liquidation calculations | Execution |
| `market:realtime` | Access real-time order flow and order book depth feeds | Stream |
| `trading:read` | Read bot states and trade logs | Read-Only |
| `trading:execute` | Create or modify automated trading bot instances | Read/Write |

---

## 4. API Request Authentication

All API requests must include the bearer token or API key in the `Authorization` HTTP header:

```http
GET https://tradingmaster.app/api/v1/strategies HTTP/1.1
Host: tradingmaster.app
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json
```

For Markdown content negotiation, agents may also specify:
```http
Accept: text/markdown
```

---

## 5. Token Revocation & Claim

- **Revocation Endpoint**: `https://tradingmaster.app/api/auth/revoke`
- **Claim Agent Dashboard**: `https://tradingmaster.app/auth/claim-agent`
- **Security Contact**: `security@tradingmaster.app` (RFC 9116: `/.well-known/security.txt`)