Server-to-server API

Not every app has a UI inside RentalTide. A GPS/telematics service, an AI phone agent, an accounting sync, or a data pipeline runs on your servers and talks to RentalTide directly. That's what the /api/v1 partner gateway is for.

Your app authenticates with its OAuth installation access token and calls the real RentalTide API paths under /api/v1. Every call is scope-checked; your app acts within the merchant's account at the scopes they granted.

GET https://app.rentaltide.com/api/v1/schedule?limit=5
Authorization: Bearer <oauth-access-token>

Get a token

Run the standard OAuth flow (see Build your first app):

1. Redirect the merchant to /oauth/authorize?... with the scopes you need.
2. Exchange the returned code at POST /oauth/token for an access token (1-hour) and a refresh token (90-day). Refresh with grant_type=refresh_token before expiry.

The with-backend example implements the callback + token exchange.

Call the API

Use the access token as a Bearer token against /api/v1 + any documented path:

The gateway forwards to the same endpoints documented in the API reference — just prefix them with /api/v1.

Scopes & access

Each path requires a scope (see Scopes). Calls without the scope return 403 insufficient_scope with the requiredScope that was missing. Paths that aren't exposed to apps (account/billing management, staff administration, integrations config, file uploads) return 403 regardless — the gateway is default-deny.

Available families: bookings, customers (renters), inventory, POS, transactions, analytics (read), reports (read), and locations/geofence. Voice calling uses the audio_calling scope (see below).

Rate limits

The gateway allows 600 requests/minute per installation. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Back off on 429.

Provider playbooks

GPS / telematics provider

• read:inventory → map your devices to assets (GET /api/v1/inventory, /asset-pools).
• read:geofence / write:geofence → read positions and geofences, push updates (/api/v1/geofences, /api/v1/staff-locations).
• Subscribe to booking.checked_in / booking.status_changed webhooks to trigger geofencing when an asset goes out.
• Or render a live map in-app at the asset-tracking embed location.

AI phone provider

• audio_calling → initiate/manage calls (/calls/partner/*).
• read:customers → look up the caller (GET /api/v1/renters).
• read:bookings / write:bookings → check availability and create the booking during the call (/api/v1/schedule).

Choosing embedded vs server-to-server

• Embedded app (iframe + App Bridge SDK): you want UI inside RentalTide. Token handling is automatic; calls go through the host.
• Server-to-server (/api/v1): you run your own backend with no RentalTide UI, or you need to act outside a logged-in session (background jobs, inbound calls, device callbacks).

Many apps use both — an embedded panel for staff plus a backend that reacts to webhooks and calls /api/v1.