Authentication

Overview

BookyFlow uses OAuth2 for API authentication. You'll need to obtain an access token before making API requests to protected endpoints.

Authentication Methods

Core API Access

For basic BookyFlow operations, you need:

• Client ID - Obtained from the BookyFlow control panel
• Client Secret - Obtained from the BookyFlow control panel
• Access Token - Generated using your credentials

Channel Management Framework (CMF) Access

For channel management operations, after obtaining a token you must:

1. Announce your channel using the Announce endpoint
2. Include X-BOOKYFLOW-channel-name header in all subsequent requests
3. Only access properties you have created

Getting an Access Token

Request

POST /bookyflow/api/oauth/token
Content-Type: application/x-www-form-urlencoded

Parameters

Example Request

curl -X POST https://yourdomain.com/bookyflow/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read write"

Example Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Access Token

Include the access token in the Authorization header of your requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example Request

curl -X GET https://yourdomain.com/bookyflow/api/properties \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API Scopes

When creating API credentials, you must specify which scopes (permissions) the key should have. Scopes are defined in each API plugin's scopes.json file.

Common scopes include:

• read - Read access to resources
• write - Create and update resources
• delete - Delete resources

Auth-Free Endpoints

Some API endpoints do not require authentication and are marked with an asterisk (*) in this documentation. These endpoints can be accessed without an access token.

Important Guidelines

Date Format

All dates must be sent in YYYY-MM-DD format.

Example: 2024-11-17

Variable Replacement

Replace @variable_name placeholders with actual values:

• @property_id → actual property UID
• @booking_id → actual booking ID
• etc.

HTTP Methods

The API follows RESTful conventions:

• GET - Retrieve information
• POST - Create new records
• PUT - Update existing records
• DELETE - Remove records

Security Best Practices

1. Keep Credentials Secure - Never expose your Client ID and Secret in client-side code
2. Use HTTPS - Always use HTTPS for all API communications
3. Token Expiration - Tokens expire after 1 hour; request a new token when needed
4. Rotate Credentials - Periodically rotate your API credentials
5. Minimal Scopes - Request only the scopes your application needs

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "error_description": "Invalid or expired token"
}

Solution: Request a new access token.

403 Forbidden

{
  "error": "forbidden",
  "error_description": "Insufficient scope"
}

Solution: Ensure your API key has the required scopes.