Skip to main content

​
What are API Keys?

API keys allow you to authenticate requests to the Kordless API from your applications. Each key is scoped to your organization and provides programmatic access to manage bookings, availability, and services.
API keys provide full access to your organization’s data. Treat them like passwords and never share them publicly or commit them to version control.

​
Creating an API Key

1

Navigate to API Keys

Go to Settings → Integration → API Keys in the platform.
2

Generate New Key

Click Generate API Key and provide:
  • Label: A descriptive name (e.g., “Production App”, “Mobile App”)
  • Environment: Development or Production (optional)
3

Save Your Key

Copy and save your API key immediately! For security reasons, you won’t be able to view it again.
Store the key securely in your application’s environment variables or secrets manager.

​
Using Your API Key

Include your API key in the x-kordless-key header of all API requests: 
curl https://api.kordless.ai/api/calendar/v1/bookings \
  -H "x-kordless-key: your_api_key_here" \
  -H "x-organization-id: your_org_id"

const response = await fetch('https://api.kordless.ai/api/calendar/v1/bookings', {
  headers: {
    'x-kordless-key': process.env.KORDLESS_API_KEY,
    'x-organization-id': 'your_org_id'
  }
});

​
Finding Your Organization ID

Your organization ID is required for all API requests. Find it in:
  • Settings → Organization → Organization ID
  • Or extract it from your Clerk organization ID (it’s the part after org_)

​
Best Practices

Never hardcode API keys in your source code. Use environment variables or a secrets manager:
// ✅ Good
const apiKey = process.env.KORDLESS_API_KEY;

// ❌ Bad
const apiKey = "kord_live_abc123...";
Generate new keys periodically and revoke old ones:
  • Every 90 days for production
  • Immediately if a key is compromised
  • When team members with access leave
Create separate keys for:
  • Local development
  • Staging/testing
  • Production
This makes it easier to identify which environment made a request and limits damage if a development key is exposed.
Regularly review API usage in your dashboard:
  • Check for unusual activity
  • Identify which keys are actively used
  • Monitor rate limits and quotas

​
Managing API Keys

​
Viewing Keys

See all your organization’s API keys in the API Keys dashboard. Each key shows:
  • Label
  • Environment
  • Created date
  • Last used date
  • Status (active/revoked)
For security, you can only view the full key value when it’s first created. After that, only the last 4 characters are displayed.

​
Revoking Keys

If a key is compromised or no longer needed:
1

Identify the Key

Locate the key in your API Keys list by label or last 4 characters.
2

Revoke

Click the Revoke button next to the key.
3

Confirm

Confirm the revocation. The key will immediately stop working.
4

Update Applications

If the key was in use, update your applications with a new key before revoking to avoid downtime.
Revoking a key is immediate and cannot be undone. Any applications using that key will lose access.

​
Rate Limits

API keys are subject to rate limits to ensure fair usage:
  • 100 requests per minute per API key
  • 1,000 requests per hour per API key
  • 10,000 requests per day per organization
If you need higher limits, contact us.

​
Rate Limit Headers

API responses include rate limit information: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

​
Troubleshooting

Cause: Invalid or missing API keySolution:
  • Check that the x-kordless-key header is included
  • Verify the key hasn’t been revoked
  • Ensure you’re using the correct key for your environment
Cause: API key valid but lacks permission for the requested resourceSolution:
  • Verify the x-organization-id header matches your organization
  • Check that the resource belongs to your organization
Cause: Rate limit exceededSolution:
  • Implement exponential backoff
  • Cache responses when possible
  • Optimize your request patterns
  • Contact us for higher limits if needed

​
Next Steps

API Authentication

Learn more about API authentication and security.

Make Your First Request

Start using the Booking API.

Set Up Webhooks

Receive real-time notifications for booking events.

API Reference

Explore all available API endpoints.