​
Introduction

Certain PMS providers support OAuth connections. This allows for a better, and more secure way to connect to their platform. Currently, the following PMS providers support OAuth connections:

  • HOSTFULLY
  • BOOKINGSYNC

​
OAuth Flow

The OAuth flow in Zepl follows the standard OAuth 2.0 authorization code flow. Here’s how it works:

​
Creating an OAuth Connection

To create an OAuth connection, you will need to create an OAuth Application. For each PMS provider, you will need to create a new OAuth Application, and this is a one-time process. The OAuth Application will be used when creating an integration account for the PMS provider, to generate and refresh tokens.

​
Creating an OAuth Application

Documentation for creating an OAuth application can be found in the API Reference.

When creating an OAuth application, you need to specify the required scopes that your application needs. These scopes are stored with the OAuth application and will be requested during the authorization flow. The scopes determine what level of access your application will have to the PMS provider’s resources.

Once an OAuth application is created, you will be able to create integration accounts for the PMS provider.

​
Creating an Integration Account

When creating an integration account with authType set to OAUTH, you will need to provide the following parameters:

  • name: The name of the integration account.
  • accountIdentifier: The identifier for the integration account. This should be the same as the accountIdentifier used in the OAuth application.
  • provider: The PMS provider.
  • authType: Should be set to OAUTH.
  • clientRedirectURL: The final URL that the user will be redirected to after the OAuth flow is complete. This is different from the redirectURL used in the OAuth application. The redirectURL specified there, is used for sending the OAuth callback. It should be set to {BASE_ZEPL_URL}/api/v1/oauth/callback. This clientRedirectURL should be used as a final redirect for when the Zepl platform completes the OAuth flow.

Documentation for creating an integration account can be found in the API Reference.

​
Client Redirect URL Behavior

When the OAuth flow completes, Zepl will send a POST request to your clientRedirectURL with the following information:

{
  "success": true,
  "integrationAccount": {
    "id": "db22a4d2-f1d0-4141-8feb-66fc933e39c1",
    "name": "test-bookingsync-account",
    "workspaceID": "440ba8fa-3270-4f8b-b4f0-72d5c26bca9b",
    "tenantID": "50f7d2ea-4d96-45b9-99ce-35b7960e1bc7",
    "provider": "BOOKINGSYNC",
    "providerAccountID": "18464",
    "accountIdentifier": "bookingsync",
    "authType": "OAUTH",
    "defaultDiscountPercentage": 0,
    "markupPercentage": 0,
    "distributionMarkupPercentage": 0,
    "allowImport": true,
    "status": "ACTIVE",
    "createdAt": "2025-05-16T20:38:07.794Z",
    "updatedAt": "2025-05-16T20:38:07.794Z",
  }
}

If the OAuth flow fails for any reason, the POST request will include:

{
  "success": false,
  "error": "Redirect URL mismatch"
}

Make sure your clientRedirectURL endpoint is prepared to handle both success and failure cases.

​
Troubleshooting

Common issues and their solutions:

  1. Invalid Redirect URI: Ensure the redirect URI matches exactly what’s configured in the PMS provider
  2. Scope Issues: Verify that all required scopes are requested during the OAuth flow