Skip to content

API Reference

Authentication

API key types, Bearer authentication, and session token exchange.

API Key Types

Full API access requires the Pro plan. Pro

Widget publishable keys are available on all plans.

Calendence uses four types of API keys, each with different access levels:

Type Prefix Use Case
Hub cal_hub_ Full access to all businesses under a Hub
Business cal_biz_ Full access to a single business
Publishable cal_pub_ Widget embedding — can only create booking sessions
Session cal_ses_ Short-lived token for active booking sessions

Bearer Authentication

All API requests require a Bearer token in the Authorization header:

curl -X GET https://calendence.com/api/v1/services \
  -H "Authorization: Bearer cal_biz_your_api_key"

Session Token Exchange

The booking widget uses a two-step authentication flow:

  1. The widget sends the publishable key to exchange for a session token
  2. The session token is used for all subsequent API calls during the booking flow
# Step 1: Exchange publishable key for session token
curl -X POST https://calendence.com/api/v1/session \
  -H "Authorization: Bearer cal_pub_your_publishable_key"

Response:

{
  "session_token": "cal_ses_abc123...",
  "expires_at": "2026-03-24T05:00:00+00:00",
  "business": {
    "id": "uuid",
    "name": "Demo Auto Detail",
    "timezone": "America/Chicago"
  }
}

Session tokens expire after 1 hour and are automatically refreshed by the widget.

Rate Limits

Burst Limits (per minute)

Endpoint Growth Pro
Session exchange (/session) 20 requests/minute per IP 20 requests/minute per IP
API endpoints 30 requests/minute per key 60 requests/minute per key

Sustained Limits (per hour)

Endpoint Growth Pro
API endpoints 300 requests/hour per key 1,000 requests/hour per key

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1711324800
  • X-RateLimit-Limit — Maximum requests allowed in the current window.
  • X-RateLimit-Remaining — Requests remaining in the current window.
  • X-RateLimit-Reset — Unix timestamp when the current rate limit window resets.

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.