Building a Marketplace App

Use a marketplace app when your platform lists and sells rental inventory on behalf of Lockii operators. Operators connect your marketplace, choose which products to publish, and you push paid bookings into Lockii after you collect payment from the renter.

If you are building an accounting sync, automation tool, or other integration that is not a sales channel, see Building a Lockii App instead.

Get listed

Marketplace apps are reviewed before launch. Email [email protected] to finish your app review. You can start developing today without needing to contact us.

Include:

• Your company and marketplace name
• A short description of the integration
• Your logo (square, PNG or SVG)
• One or more HTTPS OAuth redirect URIs
• Your connect URL (the page on your platform where an operator starts the connection)
• Your webhook HTTPS endpoint

Once approved, Lockii registers your app and issues:

• A client_id and client_secret
• A webhook signing secret

Treat the client_secret like a password. Store it in a secrets manager. Never put it in client-side code or version control. Rotation is available on request.

How it works

Connect operator → Discover listings → Check availability → Get price for dates → Take payment → Create booking

Important behaviours:

• Availability is not a stock number. It depends on start/end time, location, existing reservations, and buffer times. Always re-check near booking. Never cache it as a static quantity.
• No holds. Availability and pricing endpoints are informational. The binding capacity check happens when you create the booking.
• Use Lockii pricing for hire totals. Listing pricing_summary.from_amount is for "from $X/day" display only. Once a renter picks dates, call POST /channel/pricing for the catalogue total. Do not reimplement pricing tiers on your side.
• Auto-confirm with pending fallback. If capacity is free, the booking is confirmed. If not (for example another booking landed in between), it is created as pending_approval and the operator decides. Handle both outcomes.
• Channel-only tokens stay on the Channel API. Connections granted only channel:read and channel:write can call /api/v1/channel/* routes. They cannot call the operator Standard API (bookings, stock, customers, webhooks, or MCP). If you need that data, build a Lockii App with the right operator scopes instead.
• Instant confirmation emails are skipped. Lockii does not send the operator's instant post-confirm email for bookings created through your marketplace app. You notify the renter on your side. Timed reminders and other automated messages still send from Lockii as configured by the operator.

Base URLs

Scopes

Request only what you need:

Marketplace apps should request only channel scopes. Operator scopes (booking:read, booking:write, inventory:write, reporting:read) are for non-marketplace Lockii apps.

OAuth connection flow

Lockii uses the OAuth 2.0 authorization code grant with refresh tokens. Each successful grant creates a connection for one operator. PKCE (S256) is supported and recommended.

1. Authorization request

While the operator is logged in on your platform, redirect them to:

https://dash.lockii.app/api/oauth/authorize
  ?client_id={your client_id}
  &redirect_uri={one of your registered redirect URIs}
  &response_type=code
  &scope=channel:read channel:write
  &state={opaque anti-CSRF value}
  &external_account_id={your seller account ID}
  &external_account_name={display name, optional}

external_account_id is required for marketplace apps. It is your identifier for the seller account starting the connection. Lockii stores it on the connection and echoes it in the API and webhooks.

Operators can also start from Settings → Integrations in Lockii if you provided a connect URL.

2. Consent

The operator signs in to Lockii, picks a company, and approves the scopes.

• Approved → redirect to your redirect_uri with ?code=...&state=... (code expires in 10 minutes, single-use)
• Declined → ?error=access_denied&state=...

Always verify state before continuing.

3. Token exchange

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={code}
&client_id={client_id}
&client_secret={client_secret}
&redirect_uri={same redirect_uri as authorize}

Response includes access_token, refresh_token, expires_in, scope, and connection_id. Store the token pair against your seller account, keyed by connection_id.

Authorization codes are single-use. If your token exchange fails, send the operator through the authorize flow again instead of retrying the same code.

4. Refresh tokens

• Access tokens last 60 minutes
• Refresh tokens last 90 days and rotate on every use. Always persist the new refresh token atomically
• Reusing an already-rotated refresh token revokes the connection's tokens (replay protection)

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={current refresh token}
&client_id={client_id}
&client_secret={client_secret}

Refresh a few minutes before expiry, or on a 401 with error.code: "token_expired".

5. Pause, disconnect, reconnect

• Operators can pause or disconnect from Lockii at any time
• Paused connections return 403 with connection_paused
• Disconnect revokes tokens and sends connection.disconnected. Stop showing their listings immediately
• Running authorize again for the same operator/seller pair reuses the existing connection_id and publications, with fresh tokens
• You can revoke with POST /api/oauth/revoke (RFC 7009)

Channel API

Send the connection access token on every request:

Authorization: Bearer <access_token>

The token identifies the connection. You do not pass a company id.