API v3 Client Types

Overview

The Bookingkit API v3 supports two distinct types of clients, each designed for different use cases and integration scenarios. Understanding these client types is crucial for proper API integration and scope management.

Client Type Categories

1. Marketplace Clients

Purpose and Use Cases

Marketplace clients are designed for third-party applications and integrations that need to access data across multiple vendors or provide marketplace functionality.

Key Characteristics

• Multi-vendor Access: Can access data from multiple vendors within the Bookingkit ecosystem
• IP Restrictions: May have whitelist restrictions for enhanced security
• Admin-level Scopes: Can request broader scopes like orders_read_all and orders_write_all
• Audience: External applications, aggregators, and marketplace platforms

Typical Scopes

calendar_read orders_read_all orders_write_all calendar_write inventory_write

Security Considerations

• IP Whitelisting: Contact Bookingkit support to configure IP restrictions
• Scope Validation: Strict validation of requested scopes
• Rate Limiting: Monthly request limits apply
• Audit Trail: All requests are logged and monitored

Example Use Cases

• Travel Aggregators: Displaying events from multiple vendors
• Booking Platforms: Managing bookings across different service providers
• Analytics Services: Collecting data from multiple vendors
• Payment Processors: Handling payments for various vendors

2. Vendor Clients

Purpose and Use Cases

Vendor clients are designed for direct vendor integrations, allowing vendors to manage their own events, orders, and inventory through the API.

Key Characteristics

• Single Vendor Access: Limited to data belonging to the authenticated vendor
• Numeric User ID: Uses the vendor's numeric ID for authentication
• Owned Scopes: Primarily uses _owned scopes (e.g., orders_read_owned)
• Direct Integration: Direct connection between vendor systems and Bookingkit

Typical Scopes

calendar_read calendar_write orders_read_owned orders_write_owned inventory_write

Security Considerations

• Vendor Isolation: Can only access their own data
• Scope Restrictions: Cannot access other vendors' data
• Direct Authentication: Uses vendor credentials directly

Example Use Cases

• Vendor Management Systems: Managing events and bookings
• POS Integration: Connecting point-of-sale systems
• Inventory Management: Syncing product catalogs
• Booking Management: Handling reservations and orders

Client Type Comparison

Feature	Marketplace	Vendor
Multi-vendor Access	✅ Yes	❌ No
IP Restrictions	✅ Yes	❌ No
Admin Scopes	✅ Yes	❌ No
Owned Scopes	✅ Yes	✅ Yes
Inventory Write	✅ Yes	✅ Yes
Payment Management	✅ Yes	✅ Yes
User Management	✅ Yes	❌ No

Implementation Guidelines

Choosing the Right Client Type

1. Marketplace Integration: Use marketplace clients for multi-vendor applications
2. Direct Vendor Integration: Use vendor clients for single-vendor management

Security Best Practices

Marketplace Clients

• Implement IP whitelisting
• Use minimal required scopes
• Monitor API usage closely
• Implement proper error handling

Vendor Clients

• Secure vendor credentials
• Use owned scopes when possible
• Implement proper data validation
• Monitor for unauthorized access

Support and Configuration

Getting Started

1. Contact Support: Reach out to bookingkit support
2. Client Registration: Register your client with the appropriate type
3. IP Whitelisting: Set up IP restrictions (marketplace clients)
4. Testing: Test with sandbox environment

Understanding the different client types is essential for proper API integration. Choose the appropriate client type based on your use case, and ensure you request only the necessary scopes for your application. Always follow security best practices and contact Bookingkit support for configuration assistance.