If you are a Premium Customer

This section does not apply to you. You can skip it 🎉

If you are a Partner Integration

Entrypoint to the OAuth flow

There are 2 ways how Hostfully Customer can start the process of authorizing your integration.

1. From Hostfully PMP, on Integrations or Channels page
2. From your system

Starting authorization process from Hostfully PMP

You will be requested to provide a redirect link, that will redirect the Hostfully Customer to your system, where the Customer can initiate the OAuth process of authorizing your integration to access it's data. See "Connect with Hostfully" section for more information.

Starting authorization process from Partner System

You should have a place in your system, where the Customer can initiate the OAuth process of authorizing your integration to access it's data. See "Connect with Hostfully" section for more information.

Connect with Hostfully

In your system, you need to provide an entrypoint into the OAuth 2.0 Flow. We recommend creating a button that says Connect with Hostfully. Here's our icon in SVG format for your UI, you can right-click it and download it.

Our team verifying your Connect with Hostfully button is part of the process to be granted access for production environment.

The OAuth flow:

Below is our OAuth flow visualized for you.

Hostfully Auth Service will authenticate the users if need be, and show the users a typical authorization dialogue window to grant or decline Partner access to their data.

Steps important to you as a Partner in here are:

1. Call the Hostfully Authorization endpoint with the following parameters to initiate the OAuth flow:

   1. GET {hostfully}/api/auth/oauth/authorize with the following encoded URI parameters
      1. state - identifier provided by you to identify request on it's way back
      2. scope - 'FULL'
      3. grantType - 'REFRESH_TOKEN'
      4. clientId - your clientId
      5. redirectUri - your redirectUri that you have provided to Hostfully during the process of obtaining your secrets

2. Provide and endpoint, the {redirectUri}, that will accept the following request

   1. GET {redirectUri} with the following parameters:
      1. state - identifier provided by you to identify request on it's way back
      2. status - one of:
         1. 'INCORRECT_REQUEST' - in case the authorization request you have provided is invalid
         2. 'DECLINED' - in case Hostfully Customer will not authorize your request
         3. 'SUCCESSFUL' - in case Hostfully Customer will authorize your request
      3. code - an authorization code that you need to exchange in step 3.

3. Upon successful authorization request you need to immediately call

   1. POST {hostfully}/api/auth/oauth/code-exchange with:

      1. Basic Auth of your credentials (clientId, clientSecret)
      2. Payload

         {
           "code" : "{codeYouGotInStep2}",
           "redirectUri" : "{yourRedirectUri}",
           "scope" : "FULL",
           "grantType" : "REFRESH_TOKEN",
         }
         

   2. You will be provided with the following response:

      1. JSON

         {
           "tokens" : {
         	"accessToken" : "{accessTokenToUseForThatClient}",
           	"refreshToken" : "{refreshTokenToUseForThatClient}"
           }
         }
         

Refreshing tokens

Afterward you obtain the tokens you're in the need of refreshing the access token whenever it expires. Token is a Hostfully-signed JWT, so you can check it's validity by checking the JWT 'exp' claim.

Once token is expired you're going to get 401 response from Hostfully API while using it. Access token expires every 24 hours.

In order to refresh access token, do the following:

1. 1. POST {hostfully}/api/auth/oauth/token-refresh with

      1. Basic Auth of your credentials (clientId, clientSecret)
      2. JSON

         {
           "refreshToken" : "{refreshTokenForThatClient}"
         }
         

   2. You will be provided with the following response:

      1. JSON

         {
           "tokens" : {
         	"accessToken" : "{newAccessTokenToUseForThatClient}",
           	"refreshToken" : "{newRefreshTokenToUseForThatClient}"
           }
         }
         

Please notice that the refresh token also changes upon every access token change. If you don't persist it, the authorization granted to you becomes invalid.