API v3 Authentication

Overview

The Bookingkit API v3 uses OAuth 2.0 for authentication and authorization. This document provides comprehensive information about how to authenticate with the API and the available scopes for different types of access.

Authentication Flow

The API v3 supports Client Credentials grant type, which is suitable for server-to-server communication where the client application can securely store its credentials.

Base URLs

Production Environment

• Production API: https://api.bookingkit.de
• Token Endpoint: https://api.bookingkit.de/oauth/token
• API Base: https://api.bookingkit.de/v3

Please check the Environments page for addresses of other environments.

Getting Access Tokens

Request Format

To obtain an access token, make a POST request to the token endpoint:

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

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Example Requests

Using cURL

curl -X POST https://api.bookingkit.de/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"

Using PHP

$curl = curl_init('https://api.bookingkit.de/oauth/token');
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
    $curl,
    CURLOPT_POSTFIELDS,
    [
        'client_id' => 'your_client_id',
        'client_secret' => 'your_client_secret',
        'grant_type' => 'client_credentials',
    ]
);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);

Response Format

{
  "access_token": "134e8b2683a0e3b27dbb9420062b62eaf1d66f02",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "calendar_read orders_read_all"
}

Note: One active token per client per hour is available. You can find more information here.

Using Access Tokens

Authorization Header (Recommended)

Include the access token in the Authorization header:

GET /v3/events
Authorization: Bearer YOUR_ACCESS_TOKEN

Example with cURL

curl -X GET https://api.bookingkit.de/v3/events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example with PHP

$curl = curl_init('https://api.bookingkit.de/v3/events/');
curl_setopt(
    $curl,
    CURLOPT_HTTPHEADER,
    ['Authorization: Bearer YOUR_ACCESS_TOKEN']
);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);

Query Parameter (Alternative)

You can also pass the token as a query parameter:

GET /v3/events?access_token=YOUR_ACCESS_TOKEN

Note: Using the Authorization header is recommended for security reasons. Do not use both the Authorization header and the access_token query parameter together.

Available Scopes

The API v3 provides different scopes to control access to various resources. Scopes are organized by functional areas:

Calendar Management

• calendar_read: Allows reading event dates, availability, and calendar information
• calendar_write: Allows creating, updating, and deleting event dates and calendar entries

Order Management

• orders_read_owned: Allows reading orders that belong to the authenticated vendor
• orders_write_owned: Allows creating and updating orders for the authenticated vendor
• orders_read_all: Allows reading all orders across all vendors (marketplace access)
• orders_write_all: Allows creating and updating orders for any vendor (marketplace access)
• orders_custom_prices: Allows setting custom pricing for orders
• orders_vouchers_write_all: Allows creating and updating voucher orders for any vendor (marketplace access)
• order_read_fees: Allows reading order fees and billing information

Inventory Management

• inventory_write: Allows managing events, products, and other inventory items
• inventory_write_prices: Allows managing pricing information for inventory items

Payment Management

• write_payments_on_site: Allows adding on-site payments to orders
• write_payments_mobile_app: Allows adding mobile app payments to orders
• write_payments_third_party: Allows adding third-party payments to orders

User Management

• users_read: Allows reading user information and profiles

Voucher and Coupon Management

• voucher_validation_owned: Allows validating vouchers owned by the authenticated vendor
• vouchers_read: Allows reading voucher information and details
• coupons_read: Allows reading coupon information and details

Additional Scopes

• invoice_details: Allows access to detailed invoice information and breakdowns
• booking_channel_read: Allows reading booking channel information and analytics
• bk_fee_write: Allows managing Bookingkit platform fees and charges

Token Management

Token Expiration

Access tokens expire after 3600 seconds (1 hour). When a token expires, you'll receive a 401 Unauthorized response.

Refreshing Tokens

To get a new token, simply make another request to the token endpoint with your client credentials. There's no separate refresh token mechanism - you'll receive a new access token each time.

Best Practices

1. Store tokens securely: Never expose client secrets or access tokens in client-side code
2. Handle expiration: Implement proper error handling for 401 responses
3. Use staging for testing: Use the staging environment (api-stage.bookingkit.de) for development and testing
4. Minimize token requests: Cache tokens and reuse them until they expire
5. Use appropriate scopes: Request only the scopes your application needs

Error Handling

Common Authentication Errors

HTTP Status	Error	Description
401	Unauthorized	Invalid or expired access token
400	Bad Request	Invalid client credentials or request format
403	Forbidden	Insufficient scope for the requested resource

Error Response Format

API errors follow a consistent format with the following fields:

• message: Technical error message with details about what went wrong
• code: Numeric error code for programmatic error handling
• user_message: User-friendly error message for display

Example Error Response

{
  "message": "The parameter \"limit\" must be of type \"integer\"",
  "code": "40023",
  "user_message": "Bad Request Parameters"
}

Testing

Demo Credentials

For testing purposes, you can use sandbox credentials (check with bookingkit support for current sandbox credentials).

Support

If you have any questions about implementing authentication or need access to the API:

• Check the API documentation for endpoint-specific authentication requirements
• Contact bookingkit customer support

Additional Notes

• Vendor API Access: Some endpoints are only available when authenticated as a vendor API client. You can find more information on API clients here.