# auth.md

How an AI agent signs a guest in at **17John Hotel** (https://www.17john.com).

## Most things need no sign-in

The website, `https://www.17john.com/llms.txt` and the public MCP server at `https://www.17john.com/mcp` are open. Use them to answer questions about rooms, amenities, events and how to book (bookings happen at https://www.17john.com/book).

## What signing in gives you

One protected MCP server, `https://www.17john.com/mcp/guest`, with one tool: `whoami`, which returns the guest's email address as verified by 17John Hotel. It does not expose bookings, payments or any other guest data. Guests receive links to their booking by email, and those links stay the way to reach it.

## Audience

An agent acting for a person who can read email sent to their own address. There is no account to create and no password.

## Registration

Register a client with OAuth 2.0 Dynamic Client Registration (RFC 7591): `POST https://www.17john.com/oauth/register` with your `redirect_uris`, `client_name` and `token_endpoint_auth_method` (`none` for public clients, `client_secret_post` for confidential ones).

## Signing in (authorization code + PKCE)

1. Send the person to `https://www.17john.com/oauth/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `state`, `scope=identity` and an S256 `code_challenge`.
2. They enter their email address. A six-digit code is emailed to it; they type it in. That proves they read that mailbox.
3. We redirect to your `redirect_uri` with `code` and `state`.
4. Exchange the code at `https://www.17john.com/oauth/token` (`grant_type=authorization_code`, with your `code_verifier`). You get an access token (1 hour) and a refresh token (30 days).

## Using the credential

Send `Authorization: Bearer <access_token>` to `https://www.17john.com/mcp/guest`. Without a valid token it answers `401` with a `WWW-Authenticate` header pointing at its protected-resource metadata. Revoke a token at `https://www.17john.com/oauth/revoke` (RFC 7009).

## Personal agents (Personal Agent Protocol 0.3)

Discovery: [https://www.17john.com/.well-known/poppy.json](https://www.17john.com/.well-known/poppy.json). The issuer is `https://www.17john.com`. Both MCP servers accept DPoP (ES256).

1. Identify yourself with a client ID metadata document (`client_id` is its HTTPS URL) and authenticate with `private_key_jwt`; `aud` is the issuer, exactly.
2. Start a Session at `https://www.17john.com/oauth/token` with the JWT bearer grant and a DPoP proof (ES256). You get a signed out `DPoP` Session Token.
3. To sign the guest in, open `https://www.17john.com/oauth/authorize` in their browser with PKCE and `dpop_jkt` set to your Session Key's thumbprint. They confirm their email with a code; the redirect carries `iss`.
4. Redeem the code with your client assertion and a proof from the same key: you get an Account Token (`refresh_token`, 30 days) and a signed in Session Token (1 hour).
5. Call `https://www.17john.com/mcp/guest` with `Authorization: DPoP <token>` and a `DPoP` proof. Request tokens with `resource` set to the MCP URL you will call.
6. Sign out by revoking the Account Token at `https://www.17john.com/oauth/revoke`.

The only scope is `identity`: a signed in Session sees the guest's verified email and nothing else.

## Discovery documents

- [https://www.17john.com/.well-known/oauth-protected-resource](https://www.17john.com/.well-known/oauth-protected-resource) — protected-resource metadata (RFC 9728).
- [https://www.17john.com/.well-known/oauth-authorization-server](https://www.17john.com/.well-known/oauth-authorization-server) — authorization-server metadata (RFC 8414).
- [https://www.17john.com/.well-known/api-catalog](https://www.17john.com/.well-known/api-catalog) — catalog of agent resources (RFC 9727).
- [https://www.17john.com/.well-known/ai-catalog.json](https://www.17john.com/.well-known/ai-catalog.json) — agentic resource catalog.
