RRatesSpot
← Docs

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):

    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=…
    
    { "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.

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.