# auth.md

Agent authentication and API discovery for **Mallorca Expats Maps**.

## Audience

AI agents that search Mallorca providers, fetch life-situation guides, or submit provider leads.

## Public APIs (anonymous)

**Credential type:** none — no Bearer token required for read-only search and fetch.

| Resource | URL |
| --- | --- |
| API catalog (RFC 9727) | https://maps.mallorca-expats.de/.well-known/api-catalog |
| OpenAPI | https://maps.mallorca-expats.de/.well-known/openapi.json |
| MCP server card | https://maps.mallorca-expats.de/.well-known/mcp/server-card.json |
| Agent skills index | https://maps.mallorca-expats.de/.well-known/agent-skills/index.json |
| Machine-readable site guide | https://maps.mallorca-expats.de/llms.txt |

Endpoints:

- `GET https://maps.mallorca-expats.de/api/search?q={query}` — public search with citations
- `GET https://maps.mallorca-expats.de/api/fetch/{id}` — fetch one published document
- `POST https://maps.mallorca-expats.de/api/copilot/retrieve` — GraphRAG retrieval with citations and graph edges
- `POST https://maps.mallorca-expats.de/api/copilot/answer` — retrieve + generate a Copilot answer

## MCP

- Streamable HTTP endpoint: `https://maps.mallorca-expats.de/api/mcp`
- Read-only tools work anonymously: `search`, `fetch`, `search_providers`, `get_life_situation_plan`, `copilot_retrieve`
- Write tools (`submit_provider_lead`, checklist mutations) require OAuth Bearer tokens

## OAuth discovery

| Document | URL |
| --- | --- |
| Authorization server (RFC 8414) | https://maps.mallorca-expats.de/.well-known/oauth-authorization-server |
| Protected resource (RFC 9728) | https://maps.mallorca-expats.de/.well-known/oauth-protected-resource |
| JWKS | https://maps.mallorca-expats.de/.well-known/jwks.json |

Dynamic client registration: `POST https://maps.mallorca-expats.de/oauth/register` (RFC 7591, PKCE S256 required).

## Content policy

- AI input: yes
- AI training: no