Skip to main content

​
Overview

The Kordless Booking API uses API keys for authentication. Include your API key in every request to identify your application.
API keys grant access to create bookings for your organization. Keep them secure and never expose them in client-side code.

​
Required Header

All Booking API requests require one header: 
x-kordless-key: your_api_key_here
​
x-kordless-key
string
required
Your API key. Generate one in the platform under Calendar → Settings → API Keys.

​
Getting Your API Key

1

Navigate to API Keys

  1. Log in to the Kordless Platform
  2. Go to Calendar → Settings
  3. Scroll to the Public Booking API Keys section
2

Create a New Key

  1. Click Create new key
  2. Enter a descriptive label (e.g., “Production Website”, “Mobile App”)
  3. Click Create Key
  4. Copy the key immediately—you won’t see it again!
3

Store Securely

Use environment variables or a secrets manager:
export KORDLESS_API_KEY="your_api_key"

​
Making Authenticated Requests

curl https://api.kordless.ai/api/calendar/v1/public/org/your-org-slug \
  -H "x-kordless-key: your_api_key"

​
Organization Slug

Unlike some APIs that require an organization ID header, the Booking API identifies your organization through the URL slug: 
/api/calendar/v1/public/org/{your-org-slug}
                            ^^^^^^^^^^^^^^^
                            organization identifier
Find your slug in your public booking page URL: Your public booking page URL contains your organization slug. Find it in Calendar → Settings → Public Booking Page.

​
Customer Self-Service Authentication

For customer-facing endpoints (lookup, cancel, reschedule), authentication uses the confirmation number + contact info instead of an API key: 
# Customer looks up their booking
curl "https://api.kordless.ai/api/calendar/v1/public/bookings/confirmation/[email protected]"
​
contact
string
required
The email or phone number used when creating the booking. Used to verify the customer owns this booking.
This allows customers to manage their bookings without exposing your API key.

​
Authentication Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{
  "detail": "Missing x-kordless-key header"
}
Solutions:
  • Verify the x-kordless-key header is present
  • Check that your API key hasn’t been revoked
  • Ensure you copied the key correctly

​
403 Forbidden

Cause: API key doesn’t match the organization 
{
  "detail": "Invalid API key"
}
Solutions:
  • Verify you’re using the correct organization slug
  • Check that the API key was created for this organization
  • Ensure the key hasn’t expired or been revoked

​
Security Best Practices

Never hardcode API keys in your source code:
// ✅ Good
const apiKey = process.env.KORDLESS_API_KEY;

// ❌ Bad - Never do this!
const apiKey = "kord_live_abc123xyz...";
Never expose API keys in client-side code. Create a backend endpoint:
// Your backend API route
app.get('/api/availability', async (req, res) => {
  const response = await fetch(
    'https://api.kordless.ai/api/calendar/v1/public/availability',
    {
      headers: {
        'x-kordless-key': process.env.KORDLESS_API_KEY
      }
    }
  );
  res.json(await response.json());
});
Your frontend calls your backend, which calls Kordless.
Create different API keys for each environment:
# Development
KORDLESS_API_KEY=kord_dev_...

# Staging
KORDLESS_API_KEY=kord_staging_...

# Production
KORDLESS_API_KEY=kord_live_...
This helps you:
  • Track which environment made a request
  • Limit damage if a development key is exposed
  • Revoke keys without affecting other environments
Generate new API keys periodically:
  • Every 90 days for production keys
  • Immediately if a key is compromised
  • When team members with access leave
Generate a new key before revoking the old one to avoid downtime.
Review your API usage regularly:
  • Check for unusual activity patterns
  • Identify which keys are actively used
  • Monitor rate limits

​
Testing Authentication

Test your setup with a simple request: 
curl https://api.kordless.ai/api/calendar/v1/public/org/your-org-slug \
  -H "x-kordless-key: your_api_key" \
  -v
Look for:
  • 200 OK: Authentication successful
  • 401 Unauthorized: Check your API key
  • 404 Not Found: Check your organization slug

​
Rate Limits

API keys are subject to rate limits:
  • 60 requests/minute per API key (general)
  • 10 requests/minute per API key (booking creation)
Rate limit headers in every response: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

​
Idempotency

For POST requests (creating bookings), use the Idempotency-Key header to prevent duplicates: 
curl -X POST https://api.kordless.ai/api/calendar/v1/public/bookings \
  -H "x-kordless-key: your_api_key" \
  -H "Idempotency-Key: unique_request_id_12345" \
  -H "Content-Type: application/json" \
  -d '{...}'
The same idempotency key returns the same result for 24 hours without creating duplicates.

​
Next Steps

Get Organization

Fetch your organization info and services.

Create a Booking

Create your first booking via the API.

API Keys Management

Learn more about managing your API keys.

Error Handling

Understand how to handle API errors.