# Open Tipitaka — Agent Authentication

## Overview

Open Tipitaka uses Google OAuth 2.0 for authentication. After authentication, the server issues a JWT (HS256) valid for 7 days.

## Authentication Flow

1. **Initiate**: `GET https://api.opentipitaka.com/auth/google`
   - Redirects to Google OAuth consent screen
   - Returns a `state` parameter for CSRF protection

2. **Callback**: `GET https://api.opentipitaka.com/auth/callback?code={code}&state={state}`
   - Exchanges authorization code for Google access token
   - Creates or updates user record
   - Returns JWT in `Set-Cookie: token=<jwt>; HttpOnly; Secure; SameSite=Lax`

3. **Use API**: Include the JWT in requests
   - Cookie: `token=<jwt>` (browser)
   - Header: `Authorization: Bearer <jwt>` (agent)

## Endpoints

| Endpoint | Auth Required | Description |
|----------|--------------|-------------|
| `GET /lookup/{word}` | No | Dictionary lookup |
| `GET /v1/search` | No | Full-text search |
| `POST /translate` | Yes | AI translation |
| `GET /v1/translations` | No | Browse community translations |
| `POST /v1/translations/sadhu` | Yes | Appreciate a translation |
| `GET /auth/me` | Yes | Get current user profile |
| `GET /health` | No | Health check |

## Discovery Metadata

- OpenID Configuration: `/.well-known/openid-configuration`
- OAuth Protected Resource: `/.well-known/oauth-protected-resource`
- OAuth Authorization Server: `/.well-known/oauth-authorization-server`
- API Catalog: `/.well-known/api-catalog`

## Rate Limits

- Translation: 10 requests/minute
- Search: 30 requests/minute
- General: 60 requests/minute