Authentication

All Bundleport API requests require authentication. This guide explains how to authenticate your requests and manage API keys securely.

API Key Authentication

Bundleport uses API key authentication. Include your API key in the Authorization header of every request:

Authorization: ApiKey YOUR_API_KEY_HERE

Getting Your API Key

1. Log in to app.bundleport.com
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Give your key a descriptive name (e.g., "Production Integration")
5. Select the appropriate scopes (permissions)
6. Copy the key immediately — it won't be shown again

Keep Your Keys Secure

API keys are sensitive credentials. Never commit them to version control or expose them in client-side code.

API Key Scopes

API keys can have different scopes that control what operations they can perform:

Scope	Description
hotels:search	Search for hotel availability
hotels:quote	Recheck pricing and availability
hotels:book	Create bookings
hotels:read	Read booking details and list bookings
hotels:cancel	Cancel bookings
content:read	Access hotel content and catalog data

You can assign multiple scopes to a single API key. For example, a booking integration might need: hotels:search, hotels:quote, hotels:book, hotels:read, hotels:cancel.

Environment Types

Sandbox

• Purpose: Testing and development
• Rate Limits: Configurable per service account (default: 600/minute, 15,000/hour, 250,000/day)
• Data: Uses test suppliers and mock data
• Bookings: Not real — no actual reservations are created

Production

• Purpose: Live integrations
• Rate Limits: Configurable per service account (default: 600/minute, 15,000/hour, 250,000/day)
• Data: Real suppliers and live inventory
• Bookings: Real reservations — use with caution

Start with Sandbox

Always test your integration in sandbox before using production keys.

Request Headers

Include these headers in all API requests:

Authorization: ApiKey YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

Optional Headers

• X-Request-ID: Unique identifier for request tracing (recommended)
• X-Client-Version: Your application version (for support)
• User-Agent: Your application name (for analytics)

Code Examples

cURL

curl -X POST https://api.bundleport.com/hotels/v1/search \
  -H "Authorization: ApiKey YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: req-12345" \
  -d '{...}'

JavaScript

const headers = {
  'Authorization': 'ApiKey YOUR_API_KEY_HERE',
  'Content-Type': 'application/json',
  'X-Request-ID': `req-${Date.now()}`,
};

const response = await fetch('https://api.bundleport.com/hotels/v1/search', {
  method: 'POST',
  headers,
  body: JSON.stringify({...}),
});

Python

import requests
import uuid

headers = {
    'Authorization': 'ApiKey YOUR_API_KEY_HERE',
    'Content-Type': 'application/json',
    'X-Request-ID': str(uuid.uuid4()),
}

response = requests.post(
    'https://api.bundleport.com/hotels/v1/search',
    json={...},
    headers=headers
)

Security Best Practices

1. Store Keys Securely

• Never hardcode API keys in your source code
• Use environment variables or secret management services
• Rotate keys regularly (at least every 90 days)

2. Use Environment-Specific Keys

• Separate keys for development, staging, and production
• Different keys for different services or applications
• Revoke keys immediately if compromised

3. Monitor Key Usage

• Review API key usage in your dashboard regularly
• Set up alerts for unusual activity
• Monitor rate limit usage

4. Implement Key Rotation

// Example: Rotate keys without downtime
const apiKeys = [
  process.env.BUNDLEPORT_API_KEY_PRIMARY,
  process.env.BUNDLEPORT_API_KEY_SECONDARY,
];

let currentKeyIndex = 0;

async function makeRequest(url, options) {
  const key = apiKeys[currentKeyIndex];
  try {
    return await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `ApiKey ${key}`,
      },
    });
  } catch (error) {
    // Rotate to backup key on failure
    if (currentKeyIndex === 0 && apiKeys.length > 1) {
      currentKeyIndex = 1;
      return makeRequest(url, options);
    }
    throw error;
  }
}

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Solutions:

• Verify your API key is correct
• Check the Authorization header format
• Ensure the key hasn't been revoked

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required scope: hotels:book"
  }
}

Solutions:

• Check your API key has the required scopes
• Request additional scopes in the dashboard
• Use a different API key with appropriate permissions

Rate Limits

Rate limits are applied per service account (API key) and enforced at multiple time windows:

• Per minute: 600 requests (default)
• Per hour: 15,000 requests (default)
• Per day: 250,000 requests (default)

Rate limits are configurable per service account. Check your specific limits in app.bundleport.com or via the Core API.

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Include the Retry-After header value in your retry logic.

IP Allowlisting (Optional)

For additional security, you can restrict API keys to specific IP addresses:

1. Go to Settings → API Keys
2. Edit your API key
3. Add allowed IP addresses or CIDR ranges
4. Save changes

IP Allowlisting

IP allowlisting is optional but recommended for production environments. Ensure your server IPs are whitelisted.

Next Steps

• Error Handling Guide - Learn how to handle API errors gracefully
• Rate Limits Guide - Understand rate limiting and best practices
• Webhooks Guide - Set up webhooks for real-time notifications