# auth.md - Puerto Plaza Hotel & Shops Agent Registration & Capabilities

## Overview
Puerto Plaza Hotel & Shops provides a standardized interface for autonomous AI agents, LLM assistants, and WebMCP crawlers to discover capabilities, register, authenticate, and perform direct suite bookings and concierge actions.

- **Resource URI**: `https://puertoplazalasterrenas.com`
- **OAuth Protected Resource Metadata (RFC 9728)**: `https://puertoplazalasterrenas.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server (RFC 8414)**: `https://puertoplazalasterrenas.com/.well-known/oauth-authorization-server`
- **API Catalog (RFC 9727)**: `https://puertoplazalasterrenas.com/.well-known/api-catalog`
- **MCP Server Card (SEP-1649)**: `https://puertoplazalasterrenas.com/.well-known/mcp/server-card.json`
- **Agent Skills Discovery Index**: `https://puertoplazalasterrenas.com/.well-known/agent-skills/index.json`
- **A2A Agent Card**: `https://puertoplazalasterrenas.com/.well-known/agent-card.json`
- **Actuator Mappings Endpoint**: `https://puertoplazalasterrenas.com/actuator/mappings.json`
- **LLMs Specification**: `https://puertoplazalasterrenas.com/llms.txt`
- **Comprehensive LLMs Data**: `https://puertoplazalasterrenas.com/llms-full.txt`

---

## Agent Registration & Authentication

Autonomous AI agents authenticate with Puerto Plaza Hotel & Shops via OAuth 2.0 and the Auth.md specification.

### 1. Registration Endpoints
- **Agent Registration URI**: `https://puertoplazalasterrenas.com/api/agent/auth`
- **User Claim URI**: `https://puertoplazalasterrenas.com/api/agent/claim`
- **Credential Revocation URI**: `https://puertoplazalasterrenas.com/api/agent/revoke`
- **Token Endpoint**: `https://puertoplazalasterrenas.com/api/auth/token`

### 2. Supported Identity Types
- `anonymous`: Instant guest session for availability lookups and quotes.
- `identity_assertion`: Enterprise and verified AI agent delegations.
  - **Assertion Types**: `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`
  - **Credential Types**: `api_key`, `bearer_token`

### 3. Registration Flow
1. **Discover**: Request `/.well-known/oauth-protected-resource` to locate the authorization server.
2. **Obtain Metadata**: Inspect `/.well-known/oauth-authorization-server` for the `agent_auth` configuration block.
3. **Register / Token Request**:
   - Send `POST /api/agent/auth` with your agent identity assertion or anonymous request.
   - For public read-only operations (availability check, promenade catalog), tokens are granted immediately.
   - For confirmed booking transactions, the `claim_uri` is returned to complete guest contact confirmation.

---

## Agentic Capabilities Block
```json
{
  "name": "puerto_plaza_hotel_agent",
  "version": "1.0.0",
  "resource": "https://puertoplazalasterrenas.com",
  "mpp_support": true,
  "x403_support": true,
  "endpoints": {
    "booking": "https://puertoplazalasterrenas.com/rates-and-reservations/",
    "whatsapp_concierge": "https://wa.me/18092405544",
    "promenade_catalog": "https://puertoplazalasterrenas.com/actuator/mappings.json",
    "oauth_metadata": "https://puertoplazalasterrenas.com/.well-known/oauth-protected-resource",
    "api_catalog": "https://puertoplazalasterrenas.com/.well-known/api-catalog",
    "mcp_server": "https://puertoplazalasterrenas.com/mcp"
  },
  "actions": [
    {
      "name": "reserve_apartment",
      "method": "GET",
      "target": "https://puertoplazalasterrenas.com/rates-and-reservations/",
      "parameters": ["checkin", "checkout", "guests", "apartment_type"]
    },
    {
      "name": "inquire_concierge",
      "method": "GET",
      "target": "https://wa.me/18092405544",
      "parameters": ["text"]
    }
  ]
}
```

---

## Security & Compliance
All endpoints comply with RFC 8414, RFC 9727, RFC 9728, and ARD §3.4. Direct web purchasing and reservation affordances are powered by Machine Payment Protocol (MPP/1.0) and X403 standard web headers.