OAuth Connections

Introduction

Certain PMS providers support OAuth connections, which offer a more secure way to connect to their platform. The following PMS providers currently support OAuth:

• BOOKINGSYNC
• HOSPITABLE
• HOSTFULLY
• HOSTFULLYSANDBOX

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 the user will be redirected to once the OAuth flow completes. This is distinct from the redirectURL on the OAuth application itself — that one receives the OAuth callback from the provider and must be set to {BASE_ZEPL_URL}/api/v1/oauth/callback. clientRedirectURL is the URL Zepl redirects to after it finishes exchanging the authorization code.

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