# Kamera-ichi Authentication & Authorization Guide

This document provides technical authentication specifications and integration guidelines for developers and autonomous AI agents integrating with the Kamera-ichi API.

## Overview

Kamera-ichi offers two authentication tiers:
1. **Public Read-Only Access (No Auth Required)**: Public search, market trends, catalog discovery, OpenAPI specs, and MCP endpoints are accessible freely without credentials.
2. **Member Operations (Bearer JWT)**: Creating listings, updating profile, and sending messages require an authorized bearer token obtained with email and password in a JSON request.

## Pick a method

| Method | When to use | Credential | Cost |
|---|---|---|---|
| No auth (anonymous) | Search listings, price trends, MCP read tools, OpenAPI | none | Free |
| Bearer JWT | Member operations: create listing, messages, profile | `Authorization: Bearer <JWT>` | Free |

Agents that only read public market data should pick **No auth** and skip registration entirely.

## Register

Self-serve registration, no sales contact required:

```
POST https://kamera-ichi.com/api/auth/register
Content-Type: application/json

{"email":"agent@example.com","password":"<password>","display_name":"My Agent"}
```

## Claim

Exchange credentials for an access token:

```
POST https://kamera-ichi.com/api/auth/token
Content-Type: application/json

{"email":"agent@example.com","password":"<password>"}
```

Response contains `access_token`, `token_type: "Bearer"`, and `expires_in`. Member tokens expire after 24 hours (86400 seconds); administrator tokens expire after 1 hour (3600 seconds).

 ## Authentication Headers
 
 For authenticated endpoints, provide standard RFC 6750 bearer tokens:
 
 GET /api/users/me HTTP/1.1
 Host: kamera-ichi.com
 Authorization: Bearer <JWT_SESSION_TOKEN>
 Accept: application/json
 
## Error Model

Errors adhere to RFC 9457 Problem Details (application/problem+json):

{
  "type": "https://kamera-ichi.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "UNAUTHORIZED",
  "detail": "Missing or invalid Bearer token in Authorization header.",
  "resolution": "Please supply a valid token obtained from /api/auth/login or /api/auth/token."
}

## Errors

| Status | Code | Meaning | Agent action |
|---|---|---|---|
| 400 | BAD_REQUEST | Malformed parameters or body | Fix the request shape, do not retry blindly |
| 401 | UNAUTHORIZED | Missing or expired Bearer token | Re-claim a token at /api/auth/token |
| 403 | FORBIDDEN | Operation is not permitted for this account | Check account permissions and resource ownership |
| 404 | NOT_FOUND | Endpoint or resource missing | Check /openapi.json |
| 429 | RATE_LIMITED | Request rate exceeded | Respect Retry-After when supplied and reduce request frequency |

## Revocation

Revoke an access token immediately:

```
POST https://kamera-ichi.com/api/auth/revoke
Authorization: Bearer <JWT_SESSION_TOKEN>
```

Tokens also expire automatically. Deleting the account from /account revokes all issued tokens.

## Public Read-Only Quickstart Walkthrough
 
 1. **Step 1: Discover API & Capabilities**
    curl -s https://kamera-ichi.com/openapi.json
 
 2. **Step 2: Query Public Used Camera Listings**
    curl -s "https://kamera-ichi.com/api/listings/search?q=Sony+A74&category=camera"
 
 3. **Step 3: Query Price Trend Benchmarks**
    curl -s "https://kamera-ichi.com/api/trends/Sony/A74"
 
 4. **Step 4: Connect via Model Context Protocol (MCP)**
    curl -X POST https://kamera-ichi.com/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'