Authentication
Every call carries a bearer key:
Code
A key is made by the rental under Settings, API keys, and shown once. Only its hash is stored, so a lost key is replaced, not recovered.
What a key reaches
A key acts as one sales channel. It reaches every rental that channel sells, and GET /rentals lists them. A booking made with the key lands on that channel, which is how the rental knows who sold it and what commission applies.
A reseller that sells many companies' rentals gets one key from Mellow, not one from each rental. It reaches every rental that connected the reseller under Integrations, in any organization, on the price list and car types each rental picked. A rental that removes the reseller drops out of every answer at once. A reseller's key uses its own paths, without a rental slug: see Sell as a reseller.
A key for the whole organization acts as no one channel. It reaches every active rental of the organization, and sees the bookings of every channel. Only such a key may write prices: see Price setup. The rental makes it under Settings, API keys, with "Whole organization" as what the key acts as.
A rental may limit a channel to some car types. A key on such a channel sees only those car types, in availability, in quotes and on bookings.
Test keys
The rental can make a key in Test mode. A test key starts sk_test_ and reaches the same rentals as a live key of its channel, on their real cars and prices. It is a dry run, and nothing it does lands on the rental:
- It reads car types, locations, products, fees, availability and quotes, with the live answers. A search with it counts as no demand.
- A hold (
POST /rentals/{slug}/holds) runs every check of a live hold and is priced the same, but keeps no car. Its id startstest_. Only the key that made it reads, pays or ends it. - A payment on a test hold goes to a sandbox, never to the rental's processor. Its answer has
test: true, and the paid hold shows a test code, such asTEST-4F2A, in place of a booking. - Every other path, such as making, reading or cancelling a booking, answers
403with the codeforbidden.
A test key gets the booking set of scopes and payment.take, for its test holds alone.
Rotating a key
The rental can rotate a key: a new key under the same name, channel and scopes, and the old one revoked at once. Swap to the new key when the rental hands it over. A revoked key answers 401 for every call.
A reseller's key is rotated by Mellow. The old key then works for 7 more days, so you can swap keys without a gap.
Scopes
A key carries the scopes it was made with. Every key gets the booking set:
| Scope | What it allows |
|---|---|
fleet.read | Car types, locations, places and extras. |
price.read | Availability, quotes and prices before a booking. |
booking.read | Read the channel's bookings. |
booking.create | Make a booking. |
booking.modify | Change the dates, the locations or the car type. |
booking.cancel | Cancel a booking. |
More scopes are given only when the rental picks them as it makes the key:
| Scope | What it allows |
|---|---|
payment.take | Ask for a payment on a booking, through the rental's processor. |
affiliate.read and affiliate.write | Read the affiliates and their commissions, add an affiliate, approve or reject a commission. |
price.write | Write rates, rate periods and price rules. A key for the whole organization only. |
A call outside the key's scopes answers 403 with the code forbidden, on every path. A booking on another channel answers 404, because the key cannot see it at all.