# auth.md

Giggle Trade agent authentication guide for MCP, ACP, and AI HTTP APIs.

## Audience

AI agents and automated clients that need authenticated access to cart, orders, API keys, or other private tools. Public catalog/stock tools do **not** require auth.

## Registration methods

### 1. Verified email (identity_assertion / verified_email)

1. Register: https://giggletrade.com/auth/signup
2. Login for JWT: `POST https://giggletrade.com/api/auth/login` with JSON `{ "email", "password" }`
3. Optional API key: after login, create a key and send `X-Api-Key` on authenticated MCP/ACP calls
4. Claim / provisioning URI: https://giggletrade.com/auth/signup

### 2. Anonymous (public tools)

No registration. Use public catalog/stock/content tools and discovery docs at https://giggletrade.com/llms.txt.

## Authorization server

- Issuer: `https://giggletrade.com`
- OAuth AS metadata: https://giggletrade.com/.well-known/oauth-authorization-server
- OpenID configuration: https://giggletrade.com/.well-known/openid-configuration
- Protected resource metadata: https://giggletrade.com/.well-known/oauth-protected-resource
- JWKS: https://giggletrade.com/.well-known/jwks.json
- agent_auth skill: https://giggletrade.com/auth.md
- register_uri: https://giggletrade.com/auth/signup

## Credential use

| Credential | Header | Use |
|------------|--------|-----|
| Access JWT | `Authorization: Bearer <token>` | Authenticated MCP/ACP tools, `/api/*` proxies |
| API key | `X-Api-Key: <key>` | Same authenticated tool surface without browser session |

## Scopes (logical)

`catalog:read`, `stock:read`, `orders:write`, `mcp`, `api` — enforced by backend roles; public tools ignore credentials.

## Endpoints

- MCP: `POST https://giggletrade.com/mcp`
- ACP tools: `GET/POST https://giggletrade.com/acp/tools`
- ACP checkout sessions: `POST https://giggletrade.com/api/acp/checkout_sessions`
- Health: `GET https://giggletrade.com/health`
- Docs: https://giggletrade.com/developer/mcp

## Policies

Prefer least privilege: use public tools when possible; keep API keys secret; revoke via logout / delete_api_key when done.