Airbnb Authorization

Airbnb requires OAuth approval from the host's Airbnb account for every property. The host must sign in and grant access before ONDA can read listings, push rates and availability, and receive bookings under that account.

A vendor system cannot do this on the host's behalf; it must happen in the host's own browser. For an account that has already granted access, the approval screen is sometimes skipped and the flow completes immediately.

Prerequisites

• This applies to channels whose channel metadata sets requires_cms_authorization to true → Direct Legacy Channel Opening
• Find Airbnb's channel_id with GET /gds/vendor/channels. The examples below use 133.

When it is needed

Situation	Authorization needed
Connecting a property to Airbnb for the first time	Yes — once
The host switches to a different Airbnb account	Yes — re-authorize
Token expiry	No — ONDA refreshes it automatically

Where it sits in the overall onboarding: room type and rate plan mapping cannot proceed until authorization completes.

Property registered (integrated) → Host authorization (this guide) → Room type and rate plan mapping → Start selling

What the vendor implements

1. An entry point — put a "Connect Airbnb account" button in your admin screen. On click, call the authorization URL API and send the host to the returned url (a new window is recommended)
2. A dedicated return path — a callback path for the result (for example /airbnb/callback). ONDA returns the host there with auth_result appended, so read it from that path and branch the screen
3. Completion check — auth_result is only a display hint; confirm the actual result through the mapping lookup API

The full flow

Step 1 · Issue the authorization URL

Call GET /gds/vendor/channels/{channel_id}/authorization from the vendor server.

curl -H "Authorization: {vendor_access_token}" \
  "https://vendor.dapi.tport.dev/gds/vendor/channels/133/authorization?vendor_property_id=VP-001&redirect_url=https%3A%2F%2Fvendor.example.com%2Fairbnb%2Fcallback"

Query parameter	Required	Description
vendor_property_id	Required	The property ID in the vendor's system
redirect_url	Required	The dedicated path to return to after authorization. Only http(s) is allowed, and the pipe character (|) is not permitted. ONDA appends auth_result on return, and any query parameters the vendor added are preserved

Success response (200)

{
  "url": "https://www.airbnb.com/oauth2/auth?client_id=...&redirect_uri=...&scope=...&state=..."
}

The issued url is valid for one hour. Proceeding with an expired URL fails without returning, so issue a new one and try again.

Error responses

Status	Cause	What the vendor should do
400	Malformed redirect_url — not an http(s) URL, or contains a pipe character	Fix the request value
401	Authentication token error	Check the token
403 UnsupportedChannel	The channel does not use OAuth authorization	This channel needs no authorization
404 Property not found	The property is not yet integrated, or is not yours	Complete property registration first

Step 2 · The host authorizes

Open the issued url in a new window as-is. The host signs in with the Airbnb account to be connected and grants access.

Step 3 · Handling the return

After processing the authorization, ONDA returns the host's browser to redirect_url with a 302, appending the result as auth_result.

Return	Meaning	What to do
redirect_url?auth_result=success	Success	Confirm the real result immediately with the mapping lookup
redirect_url?auth_result=fail	Failure	Tell the host authorization failed and to try again
No return at all	Undetermined	The host abandoned the flow, or the callback never reached ONDA

Step 4 · Confirming completion

Check with GET /gds/vendor/properties/{vendor_property_id}/channels/{channel_id}/mappings.

curl -H "Authorization: {vendor_access_token}" \
  "https://vendor.dapi.tport.dev/gds/vendor/properties/VP-001/channels/133/mappings"

{
  "vendor_property_id": "VP-001",
  "channel_id": "133",
  "channel_name": "Airbnb",
  "status": "enabled",
  "channel_property_id": "123456789",
  "roomtype_mappings": [],
  "rateplan_mappings": []
}

Authorization is complete when channel_property_id holds the authorized host account ID. The mapping is saved before the success redirect (302) is sent, so after a successful return the first lookup usually shows it already.

How to judge success and failure

Observed state	Verdict	Next action
auth_result=success and channel_property_id present in the mapping	Authorized	Proceed with room type and rate plan mapping
auth_result=success but no value in the mapping	Inconsistent	Verify vendor_property_id is correct and retry the lookup once or twice. If it stays empty, treat it as a failure and re-authorize
auth_result=fail	Failed	Prompt the host to retry
No return at all	Undetermined	Run the mapping lookup once more — if a value appears it is complete, otherwise retry

The mapping lookup is the single source of truth

auth_result is only a hint for deciding which screen to show. The host can edit the browser address bar — appending ?auth_result=success by hand — so it must never be treated as evidence of a completed integration. Always confirm through the mapping lookup before showing success.

When there is no return

There are two cases, and they call for opposite handling.

Case	State in ONDA	What the vendor should do
A. The callback never reached ONDA (the host abandoned or declined on the Airbnb screen)	Nothing was created — no token, no mapping. The authorization code is single-use and simply expires	Start over by issuing a new URL
B. It reached ONDA but the browser return failed (vendor site down, window closed)	The token and mapping already exist. Only the vendor missed the return signal	The mapping lookup will show it as complete

tip

Treat a closed window or a timeout as a trigger to run the mapping lookup once more, not as confirmed failure. Only when the lookup is still empty should you treat it as incomplete (case A).

Re-authorization and account switching

Case	What ONDA does	What the vendor should know
Re-authorizing with the same account	Refreshes the token only; existing room type and rate plan mappings are kept	Nothing further to do
Re-authorizing with a different account (host change)	The property mapping switches to the new account, and all existing room type and rate plan mappings are reset to unmapped	Room type and rate plan mapping must be redone from scratch before selling can resume

warning

Switching accounts resets the mappings. When entering re-authorization, we recommend warning the host that "authorizing with a different account will reset your room type and rate plan mappings."

Implementation tips

Use a dedicated return path — with a path reserved for the authorization return (for example /airbnb/callback), arriving at that path is itself the return signal. You only need to read auth_result, with no extra marker parameter.

URL-encode redirect_url — it is a query value on the issuing API, so sending it unencoded truncates the value at :// and similar. Pass it as https%3A%2F%2F....

Open a new window and notify the parent — running the flow in a new window keeps the host's admin screen intact. Have the return path notify the parent window of the result (with window.opener.postMessage, for example) and close itself, so the parent can run the mapping lookup and show the outcome.

Cap the confirmation retries — the first lookup is usually enough, but if you retry to cover a transient failure, set a limit. Never poll indefinitely. For example, after five lookups at two-second intervals with channel_property_id still empty, treat it as a failure and prompt re-authorization.

Warn against authorizing with the wrong account — a new window shares the browser's login session, so an already signed-in account may be approved straight away. On re-authorization that counts as an account switch and resets existing mappings. We recommend telling the host to "check you are signed in with the account you want to connect" before starting.

Authorization is per property — even when one host account operates several properties, authorization runs per vendor_property_id. Issue, approve, and confirm for each property.

Issue the URL when the button is pressed — the issued URL is valid for only one hour, so issuing it in advance and storing it in a screen or email risks the host opening an already-expired link.

Common problems

Airbnb shows "You can only authorize a test app to a test user created under that same app"

The development environment runs as an Airbnb test app. A test app can only be authorized by test users created under that same app, so sign out of the real account and proceed with the test user account you were given.

It returned with auth_result=success, but the mapping lookup is empty

This combination does not occur in the normal flow, because the success redirect happens only after the mapping is saved. First check that the vendor_property_id you looked up matches the property you authorized. If it is still empty after one or two retries, treat it as a failed authorization and re-authorize. It may also be an auth_result the host typed into the address bar.

Nothing comes back at all

This is usually case A — the callback never reached ONDA — and nothing was created. Still, run the mapping lookup once: in case B the integration may already be in place. If it is empty, start over by issuing a new URL.

Room type and rate plan mappings disappeared after authorization

The authorization used a different account than before. Remapping is required.