# World of Spas auth.md

## Agent Identity & Authorization Guide

This document describes how automated AI agents, search engines, and answer engines interact with World of Spas web properties and digital resources.

### 1. Agent Audience
This guide applies to:
- Autonomous web agents and answer engines (e.g., Perplexity, ChatGPT, Claude, Gemini, Google Search).
- Shopping and price comparison agents exploring hot tubs, swim spas, cold plunges, saunas, and water care supplies.
- Automated system integrations verifying inventory, showroom hours, and filter compatibility.

### 2. Public Anonymous Access (Zero Credentials Required)
World of Spas provides open, unauthenticated read access to its complete public catalog:
- **Product Specifications & Catalogs**: `https://worldofspas.com/products` and `https://worldofspas.com/hot-tubs`
- **Showroom Information & Hours**: `https://worldofspas.com/locations/calgary` and `https://worldofspas.com/locations/edmonton`
- **Filter Compatibility Directory**: `https://worldofspas.com/store/faq`
- **Location Knowledge Base & FAQs**: `https://worldofspas.com/faq`
- **Machine-Readable Context**: `https://worldofspas.com/llms.txt`
- **API Catalog**: `https://worldofspas.com/.well-known/api-catalog`

No API key, Bearer token, or OAuth handshake is required to access public catalog pages or request `Accept: text/markdown` representations.

### 3. E-Commerce & Storefront API Access
Online store checkout, cart generation, and inventory lookups are powered by Shopify Storefront API:
- **Storefront Endpoint**: `https://worldofspas.myshopify.com/api/2025-01/graphql.json`
- **Storefront Access Token Header**: `X-Shopify-Storefront-Access-Token`
- **Access Model**: Public Storefront API token for guest carts and checkout handoffs. Agents can compose carts and generate secure checkout URLs for users without handling payment credentials directly.

### 4. Lead Capture & Consultation Inquiries
Agents assisting users with quotes, consultations, or crane delivery inquiries may submit customer inquiries via:
- **Webhook Endpoint**: `POST /api/leads` (or direct Google Sheets webhook integration)
- **Content-Type**: `application/json`
- **Payload Fields**: `name`, `email`, `phone`, `city`, `interest` (hot tub, swim spa, cold plunge), `message`.

### 5. Content Signals & Bot Policies
World of Spas declares full permissions for search indexing and AI answer generation:
- `Content-Signal: ai-train=yes, search=yes, ai-input=yes`
- `Accept: text/markdown` content negotiation is supported across all page routes.

### 6. Agent Registration & Discovery Metadata
<a id="agent-registration"></a>
Autonomous agents requiring authenticated API access or webhook callbacks may register programmatically:
- **Registration URI**: `https://worldofspas.com/api/auth/register`
- **Supported Identity Types**: `did:web`, `https`
- **Credential Types**: `bearer_token`, `api_key`
- **OAuth Authorization Server Metadata**: `https://worldofspas.com/.well-known/oauth-authorization-server`
- **OAuth Protected Resource Metadata**: `https://worldofspas.com/.well-known/oauth-protected-resource`
- **OpenID Configuration**: `https://worldofspas.com/.well-known/openid-configuration`