# WellFred auth.md

## Audience and supported access methods

This document is for AI assistants and other agents helping customers discover
and request services in Costa Rica. The public API base URL is
`https://app.wellfred.com/api/agent`.

Supported methods are anonymous public API access and a customer-controlled
email-verification handoff for booking confirmation. Agent registration is not
required: WellFred does not provision agent accounts, API keys, or bearer tokens
through this public API. There is no public `POST /agent/auth` endpoint.

WellFred does not operate an OAuth authorization server for this API and does
not publish OAuth Protected Resource or Authorization Server metadata for it.
OAuth client registration, ID-JAG identity assertions, and verified-email
assertion exchange for agent credentials are not supported. Customer email
verification below establishes a customer browser session, not an agent token.

## Anonymous access: no provisioning or credentials

Call the operations in the [OpenAPI contract](/openapi.json) directly. Send
`Accept: application/json` and, for JSON POST bodies,
`Content-Type: application/json`. No `Authorization` header, integration key,
login cookie, or registration request is needed.

Discovery is account-free. `POST /api/agent/rfqs` submits a guest quote request
with customer-provided contact information after the customer authorizes it;
it does not register an agent or issue credentials. Follow the contract's
required fields and idempotency rules. Respect rate limits and `Retry-After`.

## Customer provisioning and email-verification handoff

1. After the customer approves the offering, time, and known price/currency,
   call `POST /api/agent/booking-intents` with the contract's required booking
   fields. This prepares an expiring request and returns `confirmUrl`; it does
   not create a booking, reserve capacity, or issue a login credential.
2. Give the returned `confirmUrl` to the customer. It points to the signed
   `GET /agent/confirm/{intent}` page. Preserve the complete URL, including its
   signature and expiry; do not construct a replacement URL.
3. On that page, a customer who is not already email-verified submits their
   name and email using the provided form. Its signed
   `POST /agent/confirm/{intent}` action requires the browser's CSRF token.
   This is the customer provisioning entry point: WellFred creates a free
   customer account if needed, with disclosure, and sends an email login link.
   It is an interactive website flow, not a JSON agent registration endpoint.
4. The customer opens the emailed `/magic-login/{token}` link in their browser.
   WellFred verifies it, establishes the customer's session, and returns them
   to the saved request. The customer then submits the confirmation form;
   WellFred rechecks the booking requirements, price, and availability.

Credential use: the email login link is for the customer alone. The resulting
session cookie is used by their browser on WellFred. Agents must not request
passwords, email login tokens, or session cookies, or send these as API bearer
credentials. A supplied email address alone does not establish ownership.
The API never returns a customer login token or access to booking history.

Reuse the returned confirmation link while valid. If it expires, prepare a new
request only with the customer's approval. No provider notification or booking
is created until the verified customer confirms; provider acceptance may still
be required. Read the returned outcome before claiming a booking is confirmed.

## Discovery and passive scanning

Read this document and the [agent guide](/agents.md),
[OpenAPI contract](/openapi.json), and [API reference](/docs/api) for supported
operations. Passive scanners must not submit registration, quote, booking-intent,
or confirmation requests or follow email login links: those actions can create
state, send email, or consume credentials. Do not probe `POST /agent/auth`.