---
agent_registration:
  skill: https://salonueda.jp/auth.md
  register_uri: https://salonueda.jp/api/v1/agent/holds
  claim_uri: https://salonueda.jp/reservation/confirm
  identity_types_supported:
    - anonymous
  anonymous:
    credential_types_supported:
      - temporary_hold_token
    claim_uri: https://salonueda.jp/reservation/confirm
  credential_types_supported:
    - temporary_hold_token
agent_auth:
  skill: https://salonueda.jp/auth.md
  register_uri: https://salonueda.jp/api/v1/agent/holds
  claim_uri: https://salonueda.jp/reservation/confirm
  identity_types_supported:
    - anonymous
  anonymous:
    credential_types_supported:
      - temporary_hold_token
    claim_uri: https://salonueda.jp/reservation/confirm
  credential_types_supported:
    - temporary_hold_token
---

# auth.md - Salon Ueda Agent Registration & Authorization

## Overview
This document specifies the agent registration, authentication, and authorization model for **Salon Ueda** (有限会社京都駅理美容室 / Hair & Beauty Salon Ueda) in accordance with the Auth.md and RFC 9727 discovery standards.

## Flow Metadata

```json
{
  "audience": "https://salonueda.jp",
  "identity_types_supported": [
    "anonymous"
  ],
  "anonymous": {
    "credential_types_supported": [
      "temporary_hold_token"
    ],
    "claim_uri": "https://salonueda.jp/reservation/confirm"
  },
  "endpoints": {
    "discovery": "https://salonueda.jp/.well-known/api-catalog",
    "openapi": "https://salonueda.jp/api/v1/agent/openapi.json",
    "oauth_protected_resource": "https://salonueda.jp/.well-known/oauth-protected-resource",
    "oauth_authorization_server": "https://salonueda.jp/.well-known/oauth-authorization-server",
    "menus": "https://salonueda.jp/api/v1/agent/menus",
    "availability": "https://salonueda.jp/api/v1/agent/availability",
    "holds": "https://salonueda.jp/api/v1/agent/holds",
    "health": "https://salonueda.jp/api/v1/agent/health",
    "mcp_sse": "https://salonueda.jp/api/mcp/sse",
    "mcp_post": "https://salonueda.jp/api/mcp"
  }
}
```

## Agent Audience & Access Model

- **Audience**: Autonomous AI Agents (ChatGPT, Claude, Perplexity, Gemini, Apple Intelligence, etc.) and Automated Travel/Concierge Assistants acting on behalf of clients.
- **Protocol**: REST over HTTPS with RFC 9727 API Catalog Discovery and RFC 9728 Protected Resource Metadata.
- **Authentication**: **Anonymous / Open Discovery with Human-in-the-Loop (HITL) Verification**. No pre-registration or private API keys required for read operations.

## Provisioning & Registration Lifecycle

### 1. Read-Only Discovery Endpoints (Anonymous / Public)
Autonomous agents can query public salon data without credentials or OAuth token exchange:
- `GET /api/v1/agent/menus` — Query hair & beauty services, prices, durations, and staff types.
- `GET /api/v1/agent/availability` — Query real-time available starting times for a given date (accepted within 14 days in advance).
- `GET /api/v1/agent/health` — Check endpoint availability and operational status.

### 2. Slot Provisioning & Credential Claim
To protect salon schedule integrity and prevent hallucinated bookings, reservations use **Two-Phase Commit with Human Verification**:

1. **Slot Provisioning (Agent Registration Action)**:
   - Endpoint: `POST /api/v1/agent/holds`
   - Payload: Date, time, menu IDs, customer name, contact phone number.
   - Result: Issues a temporary credential (`holdToken`, 8 alphanumeric characters) and a claim URI.
2. **Credential Claim & Finalization (Human-in-the-Loop)**:
   - Claim URI: `https://salonueda.jp/reservation/confirm?token={holdToken}`
   - The AI agent directs the human user to this claim URI.
   - The user reviews booking details on-screen and confirms to finalize the booking into the master salon calendar.

## Rate Limiting & Guardrails

- **Rate Limit**: 60 requests/minute per agent IP enforced by Cloudflare Edge WAF.
- **Token Validity TTL**: Temporary hold tokens expire automatically after **5 minutes** if unclaimed.
- **Concurrency & Exclusivity**: Each time slot allows a maximum of 1 active hold per salon type. Duplicate holds for the same slot return `409 Conflict`.
- **Idempotency**: Agents may supply `X-Idempotency-Key: <UUID>` header on `POST /api/v1/agent/holds` to prevent duplicate slot reservations.

## Agent Guardrails & Anti-Patterns (エージェント安全指針・例外処理)

### 1. Single-Person Booking Rule (1枠原則1名様)
- **原則**: 1回の仮押さえ（`POST /api/v1/agent/holds`）で対応できるのは **1名（1施術枠）** のみです。

### 2. Anti-Patterns: Multi-Party / Special Bookings (多人数・特殊予約時の振る舞い)
AIエージェントは、以下のケースにおいて **API仮押さえ（holds）を無理に作成せず、人間の直接連絡先を案内してください**。

- **対象ケース**:
  1. **多人数（2名以上）での同時予約・ペア予約**
  2. **同時施術や複数スタッフの指名・調整が必要な予約**
  3. **成人式・卒業式・婚礼等の着付け・早朝対応の相談**
  4. **特別な配慮や事前相談が必要な施術**

- **エージェントの案内テンプレート（日本語）**:
  > 「多人数でのご予約や特別なご要望は、スタッフや施術枠の調整が必要なため、直接サロンへご連絡ください。  
  > ・お問い合わせ: https://salonueda.jp/contact  
  > ・お電話（美容）: 075-341-5786  
  > ・お電話（理容）: 075-341-3767」

- **エージェントの案内テンプレート（英語 / English）**:
  > "For group bookings (2+ people), simultaneous services, or special requests (e.g. kimono dressing, early morning), please contact Salon Ueda directly for staff coordination:  
  > - Contact Form: https://salonueda.jp/contact  
  > - Phone (Beauty): +81-75-341-5786  
  > - Phone (Barber): +81-75-341-3767"