# Apps, OAuth and the remote MCP server

There are three ways to call RatesSpot. Pick by who the software is for:

| You're building | Use |
|---|---|
| A business's own website or tool | **API keys** from that business's dashboard (API keys page). Simplest. |
| An app many businesses install (invoicing, loyalty, a channel manager) | **OAuth 2.1, confidential client**: client ID and secret, authorisation code with PKCE. |
| An AI assistant, CLI or mobile app | **OAuth 2.1, public client**: PKCE, no secret. MCP clients register themselves. |

Every installed app shows up under **Apps** in the business's dashboard, with what it can do. The owner can uninstall it at any time, and its tokens stop working at once. Changes an app makes appear in the business's Activity log as "*App name* (app)".

## Use RatesSpot from Claude (remote MCP)

Add `https://api.ratesspot.com/mcp` as a custom connector (in Claude: Settings → Connectors → Add custom connector). Claude registers itself, sends you to RatesSpot to sign in, and asks which business to connect. It then has the same tools as the local MCP server (`packages/mcp`), limited to what your role allows at that business.

For a self-hosted server, use `<your API address>/mcp`.

## Build an app (confidential client)

1. **Register it.** Dashboard → Apps → *Apps you've built*. Give a name and your redirect addresses (HTTPS, or `http://localhost` while developing). You get a `client_id` and a `client_secret` (shown once; keep it on your server).

2. **Send the business to authorise.** Make a PKCE verifier and challenge (S256), then redirect the browser to:

   ```
   https://api.ratesspot.com/oauth/authorize
     ?response_type=code
     &client_id=rs_app_…
     &redirect_uri=https://yourapp.com/oauth/callback
     &code_challenge=<base64url(sha256(verifier))>
     &code_challenge_method=S256
     &state=<random>
     &scope=bookings:read catalog:read        (optional; default: everything the person's role allows)
   ```

   They sign in to RatesSpot, choose a business and approve. They come back to your redirect address with `?code=…&state=…&iss=…`, or `?error=access_denied&state=…` if they cancelled. Check `state`.

3. **Exchange the code** (within 10 minutes; it works once):

   ```sh
   curl https://api.ratesspot.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=authorization_code -d code=… \
     -d redirect_uri=https://yourapp.com/oauth/callback -d code_verifier=…
   ```

   ```json
   { "access_token": "rs_oat_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rs_ort_…", "scope": "bookings:read catalog:read" }
   ```

4. **Call the API** with `Authorization: Bearer rs_oat_…`, exactly as with an API key. The token belongs to one business.

5. **Refresh** before the hour is up: `grant_type=refresh_token&refresh_token=rs_ort_…` (with your client credentials). Each refresh returns a new refresh token and invalidates the old pair. Refresh tokens last 90 days from their last use.

6. **Revoke** when a user disconnects in your app: `POST /oauth/revoke` with `token=…`.

To hear about changes as they happen, register a webhook endpoint with the token (`POST /v1/webhook-endpoints`, needs `settings:write`); see [webhooks](https://www.ratesspot.com/docs/webhooks.md).

## Scopes

`catalog:read`, `catalog:write`, `availability:read`, `quotes:create`, `holds:create`, `bookings:read`, `bookings:list`, `bookings:write`, `payments:write`, `checkout:create`, `settings:write`, `staff:write`.

An app never gets more than the approving person's role allows at that business: front-desk staff can't grant `settings:write`, for example.

## Discovery

- `GET /.well-known/oauth-authorization-server`: endpoints, scopes, PKCE methods (RFC 8414).
- `GET /.well-known/oauth-protected-resource/mcp`: for MCP clients (RFC 9728). An unauthenticated call to `/mcp` answers 401 with a `WWW-Authenticate` header pointing here.
- `POST /oauth/register`: dynamic client registration (RFC 7591), for public clients only. Apps with a secret are registered in the dashboard.

Apps that registered themselves are marked as such on the consent screen, so people know nobody at RatesSpot has seen them.
