---
name: Hotel Alisei Agent Authentication
description: Autonomous agent registration and authentication protocol for Hotel Alisei & Spa APIs
version: 1.0.0
issuer: https://aliseihotelspa.com
resource: https://aliseihotelspa.com
register_uri: https://aliseihotelspa.com/agent/register
identity_endpoint: https://aliseihotelspa.com/agent/identity
claim_endpoint: https://aliseihotelspa.com/agent/claim
claim_uri: https://aliseihotelspa.com/agent/claim
revocation_uri: https://aliseihotelspa.com/agent/revoke
events_endpoint: https://aliseihotelspa.com/agent/event/notify
identity_types_supported:
  - anonymous
  - identity_assertion
assertion_types_supported:
  - urn:ietf:params:oauth:token-type:id-jag
  - verified_email
credential_types_supported:
  - bearer_token
  - ephemeral_token
scopes_supported:
  - read:rooms
  - read:spa
  - read:restaurant
  - book:rooms
---

# auth.md - Hotel Alisei Agent Authentication & Registration

This document defines the agent registration and authentication protocol for autonomous AI agents, multi-agent frameworks (A2A, LangChain, AutoGen, CrewAI), and LLM assistants interacting with Hotel Alisei & Spa, Las Terrenas, Dominican Republic.

## 1. Discovery Chain (RFC 9728 & WorkOS auth.md)

1. **OAuth Protected Resource Metadata (PRM):**
   - URL: `https://aliseihotelspa.com/.well-known/oauth-protected-resource`
   - Content-Type: `application/json`
   - RFC: RFC 9728

2. **OAuth Authorization Server Metadata:**
   - URL: `https://aliseihotelspa.com/.well-known/oauth-authorization-server`
   - Contains the `agent_auth` block pointing to this file and the agent endpoints.

3. **A2A Agent Card:**
   - URL: `https://aliseihotelspa.com/.well-known/agent-card.json`
   - Agent-to-Agent discovery manifest.

4. **API Catalog (RFC 9727):**
   - URL: `https://aliseihotelspa.com/.well-known/api-catalog`

---

## 2. Supported Registration Flows

### Flow A: Agent Verified Flow (ID-JAG - Recommended)
For agents run by verified platforms (OpenAI, Anthropic, Cursor, Google Antigravity).
- **Assertion Type:** `urn:ietf:params:oauth:token-type:id-jag`
- **Mechanism:** The agent provider mints a cryptographic Identity Assertion JWT (ID-JAG). Hotel Alisei verifies the signature against the provider's JWKS and issues a scoped `bearer_token`. No human intervention required.

```http
POST /agent/register HTTP/1.1
Host: aliseihotelspa.com
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<ID-JAG-JWT-TOKEN>",
  "requested_scopes": ["read:rooms", "read:spa", "read:restaurant"]
}
```

### Flow B: Verified Email Flow
For agents operating with a verified user email address.
- **Assertion Type:** `verified_email`
- Returns an unverified credential requiring human email confirmation or claim ceremony.

### Flow C: Anonymous Start Flow
For guest agents browsing public availability and menus without prior authentication.
- **Identity Type:** `anonymous`
- **Credential Type:** `ephemeral_token`
- Scopes: `read:rooms`, `read:spa`, `read:restaurant`.
- To escalate to booking (`book:rooms`), the agent initiates a claim ceremony via `POST /agent/claim`.

```http
POST /agent/register HTTP/1.1
Host: aliseihotelspa.com
Content-Type: application/json

{
  "identity_type": "anonymous"
}
```

Response:
```json
{
  "token_type": "Bearer",
  "access_token": "alisei_anon_...",
  "expires_in": 3600,
  "scope": "read:rooms read:spa read:restaurant",
  "claim_uri": "https://aliseihotelspa.com/agent/claim"
}
```

---

## 3. Claim Ceremony & Scope Escalation

When an anonymous or unverified agent needs to book a room (`book:rooms`):

```http
POST /agent/claim HTTP/1.1
Host: aliseihotelspa.com
Authorization: Bearer alisei_anon_...
Content-Type: application/json

{
  "escalate_scope": "book:rooms"
}
```

Response:
```json
{
  "user_code": "ALI-7892",
  "verification_uri": "https://aliseihotelspa.com/verify",
  "verification_uri_complete": "https://aliseihotelspa.com/verify?code=ALI-7892",
  "expires_in": 600,
  "interval": 5
}
```

The agent displays the `verification_uri_complete` or `user_code` to the human guest. Upon confirmation, the agent exchanges the token for a booking-authorized token.

---

## 4. Revocation & Lifecycle Events

- **Revocation Endpoint:** `POST /agent/revoke`
- **Events Supported:** `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`
- **Public Keys (JWKS):** `https://aliseihotelspa.com/.well-known/http-message-signatures-directory`

---

## 5. Available API Scopes

| Scope | Description |
|---|---|
| `read:rooms` | Query apartment categories, seasonal rates, and real-time room availability. |
| `read:spa` | Retrieve Alisei Spa treatment catalog, durations, and pricing. |
| `read:restaurant` | Access El Loro Restaurant menus, daily specials, and dietary options. |
| `book:rooms` | Create apartment reservations (requires verified identity or completed claim). |

For complete interactive OpenAPI 3.1 specifications, visit [https://aliseihotelspa.com/docs/api](https://aliseihotelspa.com/docs/api).