# OAuth 2.1 for delegated booking

Canonical human page: https://aune-homepage-chat.vercel.app/docs/oauth
Canonical machine page: https://aune-homepage-chat.vercel.app/ai/oauth.md

Aune uses user-approved OAuth grants for agent booking writes. Public option search can remain anonymous; confirmation, status, cancellation, rescheduling, request creation, and webhook management require the matching scope.

## Facts

- **Issuer:** https://aune-homepage-chat.vercel.app
- **Discovery:** /.well-known/oauth-authorization-server
- **Protected resource:** /.well-known/oauth-protected-resource
- **Grant:** Authorization Code + PKCE S256
- **Access token:** Opaque, one hour
- **Refresh token:** Rotating, 30 days

## Register the exact redirect URI

Dynamic registration supports public clients and confidential clients. HTTPS redirect URIs must match exactly; loopback HTTP is accepted only for local native clients. Fragments, credentials, and wildcards are rejected.

### Dynamic client registration

```bash
curl -X POST "https://aune-homepage-chat.vercel.app/oauth/register" \
  -H "Content-Type: application/json" \
  --data '{
    "client_name": "My booking agent",
    "redirect_uris": ["https://agent.example/oauth/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "scope": "aune.bookings.search aune.bookings.confirm aune.bookings.read"
  }'
```

## Authorize with PKCE

Generate a high-entropy verifier, send its base64url SHA-256 challenge, bind the request to the Aune resource, preserve state, and show the user Aune's own consent screen. Authorization codes are one-use and expire after five minutes.

### Authorization request

```http
GET https://aune-homepage-chat.vercel.app/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https%3A%2F%2Fagent.example%2Foauth%2Fcallback
  &scope=aune.bookings.search%20aune.bookings.confirm%20aune.bookings.read
  &state=<unguessable_state>
  &code_challenge=<base64url_sha256_verifier>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Faune-homepage-chat.vercel.app
```

## Exchange and rotate

Exchange the code with the original verifier. Store tokens as credentials, never in logs or URLs. Every refresh returns a new refresh token; reuse of an older token revokes the entire token family and connected-app grant.

### Code exchange

```bash
curl -X POST "https://aune-homepage-chat.vercel.app/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "code=<one_time_code>" \
  --data-urlencode "redirect_uri=https://agent.example/oauth/callback" \
  --data-urlencode "code_verifier=<original_verifier>"
```

## Scopes

- `aune.capabilities.read`: Read Aune capabilities and supported booking types.
- `aune.bookings.search`: Search provider, price, and appointment options without contact data.
- `aune.bookings.confirm`: Confirm the exact booking option you approve.
- `aune.bookings.read`: Read the status and audit-safe details of your Aune bookings.
- `aune.bookings.cancel`: Cancel an Aune booking after fresh confirmation.
- `aune.bookings.reschedule`: Reschedule an Aune booking after choosing a fresh option.
- `aune.requests.create`: Send your contact and request details for provider follow-up.
- `aune.webhooks.manage`: Create, inspect, rotate, delete, and replay webhook delivery endpoints.

## Revocation and account control

- POST `/oauth/revoke` revokes an access token or complete refresh-token family.
- POST `/oauth/introspect` is available to authenticated confidential clients.
- Users can inspect and revoke active grants at `/connected-apps`.
- A revoked grant must fail on the next protected request; clients must not cache authorization decisions.