# auth.md

Authentication guide for Tourinform Zakarpattia API.

Base URL: https://tourinform.org.ua/api

## Registration

Register your agent to receive an API key for authenticated access:

```
POST https://tourinform.org.ua/api/agents/register
Content-Type: application/json

{
  "name": "YourAgentName",
  "version": "1.0",
  "contact": "your@email.com",
  "description": "What your agent does"
}
```

Response:
```json
{
  "agent_id": "agt_xxxxxxxxxxxx",
  "api_key": "ak_xxxxxxxxxxxx",
  "token_type": "Bearer",
  "message": "Agent registered successfully"
}
```

Use the returned `api_key` as Bearer token in subsequent requests:
```
Authorization: Bearer ak_xxxxxxxxxxxx
X-Agent-ID: agt_xxxxxxxxxxxx
```

Alternatively, identify via User-Agent header (no registration required):
```
User-Agent: YourAgentName/1.0 (contact@example.com)
```

For programmatic access via standard protocols:
- **MCP** (Model Context Protocol): `POST https://tourinform.org.ua/mcp` — no auth, JSON-RPC 2.0
- **A2A** (Agent-to-Agent): `POST https://tourinform.org.ua/a2a` — no auth, Google A2A protocol

Agent capabilities and available tools: `GET https://tourinform.org.ua/mcp`
Agent card: `GET https://tourinform.org.ua/.well-known/agent.json`

## Public endpoints (no auth required)

All catalog endpoints under `/api/catalog/*` are publicly accessible without authentication:

- `GET /api/catalog/places` — tourist attractions list (filters: search, cityName, typeSlug, categorySlug, take, page)
- `GET /api/catalog/places/:slug` — single attraction details
- `GET /api/catalog/posts` — news & articles (filters: search, cityName, tag, take, page)
- `GET /api/catalog/posts/:slug` — single article
- `GET /api/catalog/events` — upcoming events (filters: cityName, category, take)
- `GET /api/catalog/events/:slug` — single event
- `GET /api/catalog/excursions` — excursions (filters: cityName, regionName, take)
- `GET /api/catalog/excursions/:slug` — single excursion
- `GET /api/catalog/products` — craft products
- `GET /api/catalog/products/:slug` — single product
- `GET /api/catalog/guides` — certified guides
- `GET /api/catalog/search?q=` — quick search across all content
- `GET /api/catalog/cities` — cities ordered by places count
- `GET /api/catalog/featured` — recommended places for homepage

Markdown versions of individual pages (for AI agents):
- `GET /place/:slug.md` — place as Markdown
- `GET /:slug.md` — news post as Markdown

Machine-readable feeds:
- `GET /feed.xml` — RSS 2.0 feed (30 latest news)
- `GET /openapi.json` — full OpenAPI 3.0 spec
- `GET /sitemap.xml` — sitemap

## Protected endpoints

Write and admin operations (create, update, delete) require staff credentials and are not publicly accessible. Contact tourinform.news@gmail.com for partnership or data access requests.

Protected areas: `/api/places/*` (write), `/api/posts/*` (write), `/api/events/*` (write), `/bm/*` (admin panel)

## Rate limits

No hard rate limit is currently enforced. Please keep requests reasonable (max ~60 req/min per IP). Contact tourinform.news@gmail.com for bulk access.

## MCP / A2A access (no auth required)

AI agents can access all public data without authentication via:
- MCP server: `https://tourinform.org.ua/mcp`
- A2A agent: `https://tourinform.org.ua/a2a`

## OAuth Protected Resource Metadata

Machine-readable OAuth 2.0 protected resource metadata (RFC 9728):
- `GET https://tourinform.org.ua/.well-known/oauth-protected-resource`

This endpoint describes the resource server, bearer methods, and links to documentation.

---

Source: [https://tourinform.org.ua/openapi.json](https://tourinform.org.ua/openapi.json)