# auth.md

You are an agent that wants to use FlintHorn's public discovery APIs and MCP tools on behalf of a trade-business user (HVAC, plumbing, roofing). This document describes how to register and obtain credentials.

Two hosts are relevant:

- **Resource server** — `https://flinthorn.com` — public site APIs, MCP, and discovery documents.
- **Product app** — `https://newt.io` — Newt lead qualification (separate product; not covered by this auth.md).

## Discover

1. Fetch Protected Resource Metadata: `https://flinthorn.com/.well-known/oauth-protected-resource`
2. Fetch Authorization Server metadata: `https://flinthorn.com/.well-known/oauth-authorization-server`
3. Read `agent_auth` for `register_uri`, supported identity types, and credential types.

Related discovery:

- `llms.txt`: https://flinthorn.com/llms.txt
- API catalog: https://flinthorn.com/.well-known/api-catalog
- MCP server card: https://flinthorn.com/.well-known/mcp/server-card.json
- Agent skills: https://flinthorn.com/.well-known/agent-skills/index.json

## Supported method: anonymous registration

FlintHorn supports **anonymous** agent registration for read-scoped access to company info and MCP tools. No user identity is asserted.

```http
POST https://flinthorn.com/agent/auth
Content-Type: application/json

{"type":"anonymous","source":"your-agent","capabilities":["info:read","mcp:tools"]}
```

Response includes:

- `api_key` — opaque bearer credential (`fh_agent_*`). Store like an API key; do not echo into chat logs.
- `agent_id` — stable id for this registration.
- `scopes` — granted scopes.
- `resource` — audience / resource identifier (`https://flinthorn.com`).

## Use the credential

```http
GET https://flinthorn.com/api/v1/info
Authorization: Bearer $API_KEY
```

MCP Streamable HTTP endpoint: `https://flinthorn.com/mcp`

## Human contact (out of band)

For write access, paid Newt integrations, or custom agent partnerships, have the user email **hello@flinthorn.com**. Do not ask the user to paste secrets into chat.

## Revocation

Credentials may be rotated without notice. Treat `401` on a previously-working key as revocation: drop it and re-register anonymously, or ask the user to contact FlintHorn.