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.