Discover how to authenticate to Hospitable's Public API.
Hospitable protects our API endpoints using Personal Access Tokens, and OAuth 2.0's Authorization flow grants. Depending on your application use case, it might depend which authentication grant you choose to go with.
What Authentication should I use?
There are 2 forms of authentication to use the Hospitable API. Here's a short rundown on when you'd use either:
- OAuth Authorization flow for Vendors.
- Like when logging into a website with Google or Twitter, Hospitable has it's own OAuth2 Authorization flow. This allows any third-party to integrate directly with Hospitable, without requiring the user to manually share credentials insecurely. This has the added bonus of being extra secure for both Hospitable users, and developers wishing to build on our platform.
- Personal Access Tokens (PATs) for Personal API use.
- As the name suggests, typically used for Personal API access. These tokens are scoped to your Hospitable account only, and should not be shared with any third-parties. You should only use these tokens for building and testing your own Hospitable integration.
If you require any further information on which grant better suits your use case, get in touch with support.
OAuth Authorization for Vendors
If you intend on building a Hospitable integration for others, you'll need to use our OAuth2 Authorization code flow. This follows the OAuth2 standard, which you can learn more about here.
Applying to become an Approved Vendor
To get started, you'll need to request your own Vendor client credentials via this form. You'll be required to provide a:
- Technical point of contact
- Name and description of your app and the planned integration with Hospitable
- Requested scopes
- Hosted URL for your app's logo (in square format) - .png or .jpg
- A customer-facing description of what your app will do, this displays to the user
- A redirection URL (this should be inside your app, where you will handle the provided OAuth authorize code)
- A webhooks URL (where you'll receive all webhooks)
You can typically expect a response to your application within a few days. We may reach out for more information.
Once you've been issued Vendor credentials, you can start requesting access to a Hospitable user's account.
Redirecting the user to Hospitable
To get started, you'll want to create a button or link on your own app that redirects your user to the Hospitable Authorization page:
https://auth.hospitable.com/oauth/authorize?client_id=<your vendor id>&response_type=code
This will initially take the user to a login page. After they've authenticated, they will be presented with an Authorization screen to allow, or deny your application access.
Handling the redirect
When the user clicks "Authorize" they'll be redirected to the URL you provided in your application. This URL will also include a code in the query string.
https://not-hospitable.com/redirect?code=def2020087...
Using the provided code from the query string, you'll want to make a request to our OAuth2 server at https://auth.hospitable.com/oauth/token on your backend, providing your client credentials, authorization_code grant type and the provided code from the redirection. The request should look like this:
curl --request POST \
--url https://auth.hospitable.com/oauth/token \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<your vendor id>",
"client_secret": "<your vendor secret>",
"grant_type": "authorization_code",
"code": "def5020087..."
}'
With a response of:
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "eyJ0eXA...",
"refresh_token": "def502005..."
}
This will provide you with an access_token valid for 12 hours to make any API requests on behalf of that user. You can use this token in the Authorization header of any API request, like this:
curl --request GET \
--url https://public.api.hospitable.com/properties \
--header 'Authorization: Bearer <token>'
Check your database columns!
Tokens are quite large! Access tokens ~1,200 chars and Refresh tokens ~1,000 chars respectively. If your database columns aren't configured correctly, you might experience unexpected issues with accessing the API, or refreshing due to truncation.
Refreshing your access tokens
You can use this access token until it expires, upon which you'll receive a 401 Unauthenticated error on your API requests. To resolve this, you'll need to refresh your access using the refresh_token also provided in the authorization response.
curl --request POST \
--url https://auth.hospitable.com/oauth/token \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<your vendor id>",
"client_secret": "<your vendor secret>",
"grant_type": "refresh_token",
"refresh_token": "<the refresh token>"
}'
This will provide a response identical to the authorization response, with newly generated tokens. You can then cycle these tokens for however long until authentication is no longer required, or the user disconnects.
Refresh tokens expire!
If your integration doesn't refresh Access Tokens immediately after expiry (which is common in some use cases where you may not need constant API access), you'll need to be careful - Refresh Tokens expire after 90 days. We recommend refreshing all tokens on a regular interval to ensure Hosts don't need to keep re-authorising your application.
Personal Access Tokens
If you're just trying to play around with your Hospitable account programatically, we recommend using Personal Access Tokens for ease of use. These tokens are limited to basic API scopes, but for most things are perfect for personal needs.
Choose the right grant!
If you're building a Hospitable integration to be used by others, you will need to use our OAuth2 Authorization flow. We do not recommend storing other users' Personal Access Tokens.
To get started with Personal Access Tokens, start by logging into your Hospitable account and visiting your API keys section in the apps settings.
Once there, you can create and manage your Personal Access Tokens. Click "+ Add new" in the top right to create a new one, giving it any name you'd like:
After creation, you'll receive an access token. For security purposes, you'll need to enter your account's password to copy the token.
This is the only step required to gain authentication for your account. Now, any requests you make to our API should include the Authorization header, with Bearer <token> as the value.
curl --request GET \
--url https://public.api.hospitable.com/properties \
--header 'Authorization: Bearer <token>'
Migrating from v1 Client Credentials
Before you get started...
In order to exchange credentials, you'll need to apply to become an approved Vendor.
Hospitable's v1 API required the use of a Client ID and Secret, generated manually by Hospitable users and manually sent to third-party vendors. We no longer support this method for any new products.
As a large chunk of our vendors have built their integrations with this authentication method, we've built a tool to exchange a Client credentials pair for an access token and refresh token, identical to the Authorization flow– the intention here is to make migration seamless for the vendor with absolutely no impact on the user.
Be careful while exchanging!
Once a client has been exchanged, it is immediately revoked in favour of the new access and refresh token. It's imperative you test your code before running on your product environment to avoid any potential issues.
It's recommended that you put safeguards in place before migration, and contact us to schedule a migration so our team can monitor and support. Best practices include logging, taking a snapshot of existing client ids before migration, and the ability to mark an id as successfully migrate or failed. Upon successful exchange, immediately pull user information to confirm successful exchange and functioning token.
To migrate a Client credentials pair, we've built an endpoint at https://auth.hospitable.com/exchange to accept the legacy Client ID and Secret, as well as your newly minted Vendor ID. Here's how the request looks:
curl --request POST \
--url https://auth.hospitable.com/exchange \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<legacy client id>",
"client_secret": "<legacy client secret>",
"vendor_client_id": "<your vendor client id>",
"vendor_client_secret": "<your vendor client secret>"
}'
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "...",
"refresh_token": "..."
}
This response is identical to our Authorization flow, so you can build out your new Authorization implementation and the exchanger with the same database structure considerably easier.
The /exchange endpoint is rate-limited to 300 requests per minute. In order to avoid any disruption, please ensure your code falls within this limit.