Hospitable protect our API endpoints using OAuth 2.0's Client Credentials flow.

In order to use the Hospitable API, you will need a Client ID and Secret, and use both keys to generate a token. It's that token that will allow you to access the API.

Client ID and Client secrets

You can create a new pair of API keys under the Apps section of your account. Should you need more help, you can access our help documentation on our support documentation centre.

🚧

Watch out!

Your Client ID and Secret are credentials to access your Hospitable account and should be handled securely. Do not reuse the same keys across multiple applications; create a new pair for every new vendor.

Generating a new access token

Once you have your API keys, your application should request an access token from our authorization server, extract a JSON Web Token (JWT) from the response, and send that token in the headers of further API requests.

The request to do so is a POST request to https://auth.hospitable.com/oauth/token, containing a JSON payload as follows.

curl --request POST \
  --url https://auth.hospitable.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR CLIENT ID>",
    "client_secret": "<YOUR CLIENT SECRET>",
    "audience": "api.hospitable.com",
    "grant_type": "client_credentials"
}

The response to this request will be a JSON object containing an access_token.

Authenticating your API requests with the access token

The access token should be communicated in the Authorization header of API requests:

Authorization: Bearer <YOUR ACCESS TOKEN>

Access tokens have limited lifetimes. Once an access token has expired, you will receive 401 Unauthenticated responses from our API. At this point, a new access token must be generated.