# Haggle auth.md — AI Agent Authentication & Registration Guide

This document describes how autonomous AI agents, LLM copilots, and client applications discover and register for authentication on Haggle.

## Service Metadata
- **Resource Identifier**: `https://haggle.algeris.com`
- **Authorization Server**: `https://haggle.algeris.com`
- **Protected Resource Metadata**: [/.well-known/oauth-protected-resource](https://haggle.algeris.com/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata**: [/.well-known/oauth-authorization-server](https://haggle.algeris.com/.well-known/oauth-authorization-server)
- **OpenID Configuration**: [/.well-known/openid-configuration](https://haggle.algeris.com/.well-known/openid-configuration)
- **API Catalog**: [/.well-known/api-catalog](https://haggle.algeris.com/.well-known/api-catalog)
- **MCP Server Card**: [/.well-known/mcp/server-card.json](https://haggle.algeris.com/.well-known/mcp/server-card.json)

---

## Agent Registration Workflows

### 1. Anonymous / Ephemeral Onboarding
Agents operating autonomously can request ephemeral bearer tokens without pre-configured accounts:

```http
POST https://haggle.algeris.com/api/agent/register
Content-Type: application/json

{
  "agent_name": "auto-negotiator-v1",
  "identity_type": "anonymous"
}
```

**Response (201 Created):**
```json
{
  "client_id": "haggle_agent_87af92",
  "access_token": "haggle_ephemeral_...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scopes": [
    "negotiations:read",
    "negotiations:write",
    "memories:read",
    "ai:tactics"
  ]
}
```

### 2. Identity Assertion (ID-JAG / Verified Email)
Enterprise agents and delegated personal assistants can register with signed identity assertions (e.g. `urn:ietf:params:oauth:token-type:id-jag` or verified email claims):

```http
POST https://haggle.algeris.com/api/agent/register
Content-Type: application/json

{
  "agent_name": "executive-assistant-ai",
  "identity_type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<SIGNED_JWT_ASSERTION>"
}
```

### 3. Claiming & Binding Identity
```http
POST https://haggle.algeris.com/api/agent/claim
Content-Type: application/json
Authorization: Bearer <AGENT_EPHEMERAL_TOKEN>

{
  "claim_token": "<USER_DELEGATION_CODE>"
}
```

---

## Supported Scopes
- `openid`: Basic OpenID Connect identity.
- `profile`: User and profile metadata.
- `negotiations:read`: Read past negotiation sessions, tactics, and battle plans.
- `negotiations:write`: Generate new battle plans and update session states.
- `memories:read`: Query user vector memory and win flywheel benchmarks.
- `memories:write`: Record new tactics, savings, and win records.
- `teleprompter:stream`: Access live transcription and real-time counter-objection cues.
- `ai:tactics`: Run psychological leverage calculations and tactic suggestions.

---

## Bearer Token Usage
Send the obtained token in the HTTP `Authorization` header on all API requests:
```http
GET /api/negotiations HTTP/1.1
Host: haggle.algeris.com
Authorization: Bearer <access_token>
```