Authentication and keys
Key modes, scopes, IP allow-lists and safekeeping.
Every request carries an Authorization: Bearer <key> header.
GET /v1/me HTTP/1.1
Host: api.example.com
Authorization: Bearer bp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxModes
| Prefix | Mode | Sees |
|---|---|---|
bp_test_… | Sandbox | Only your own sample properties. Cannot touch real data. |
bp_live_… | Live | The real properties of the network. Only approved agencies can get one. |
A key only reaches properties of its own mode: asking for a live property with a test key gives 404 property_not_found, and the other way round.
Scopes
| Scope | Allows |
|---|---|
catalog:read | Amenity, type, place and currency catalogue |
properties:read | Read properties, photos, subscriptions; downloads |
subscriptions:write | Subscribe and unsubscribe |
calendar:read | Read the calendar and iCal |
rates:read | Read rates, availability and quotes |
reservations:read | Read holds and reservations |
reservations:write | Hold, book, change, cancel |
events:read | Read the event log |
webhooks:manage | Manage webhook endpoints and deliveries |
A call without the needed scope gets 403 scope_missing with the missing scope in detail. Give read-only systems such as reporting tools a read-only key.
IP allow-list
Give a key allowed IP addresses or CIDR ranges (e.g. 203.0.113.0/24, 2001:db8::/32). Calls from anywhere else get 403 ip_not_allowed. Use it whenever your server has a fixed address.
Safekeeping
- Keep the key on your server only; never in a browser, a mobile app or a repository.
- We store only a hash of the key, never the key. If you lose it, create a new one.
- If you suspect a leak, revoke the key on the Developer page; it takes effect immediately.