Authentication and keys
Send the key as a bearer token on every request:
Authorization: Bearer cs_live_YOUR_KEYHow keys work
- A key belongs to the business, not to a person's login. It acts with the access of the admin who created it, limited to the permissions you chose. It can never change business settings or team membership.
- A business can hold up to 10 active keys.
- Keys expire after 30 days, 90 days, 1 year, or never. Owners get warnings 14, 3 and 1 days before.
- A key unused for 90 days is revoked, after warnings 14 and 3 days before.
- If the key's creator leaves the business or stops being an admin, their keys are revoked at once and the owners are emailed. Create a replacement.
- Every key event is emailed to all owners.
Permissions
| Scope | Allows |
|---|---|
bookings:read | Bookings across the business, including guest details |
bookings:write | Creating, rescheduling, confirming, declining and cancelling bookings, and quick invites |
booking_links:read | Booking links, services, classes, resources and routing forms |
booking_links:write | Creating and editing meeting links, and turning any link on or off |
availability:read | Availability, free times, busy times and schedules |
availability:write | Weekly hours, date overrides and blocked time |
customers:read | The customer register |
customers:write | Adding, updating and erasing customers |
organization:read | The business and its team members |
analytics:read | Booking reports |
webhooks:read | Webhook endpoints and their deliveries |
webhooks:write | Creating, changing and deleting webhook endpoints |
A request outside the key's permissions gets 403 insufficient_scope.
Rolling and revoking
Roll issues a new secret with the same settings. The old one keeps working for the overlap you choose (none, 1 hour, 24 hours or 7 days), so you can deploy the new secret first. Revoke stops a key at once. Revoke all keys is the first step if a key or an account may be compromised.
Refusals
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | No key, or not a valid one |
| 401 | credential_expired | The key has expired |
| 401 | credential_revoked | The key was revoked, or its roll overlap ended |
| 402 | plan_required | The business has neither Pro nor a complimentary grant |
| 403 | ip_not_allowed | The address is outside the key's allowlist |
| 403 | api_access_suspended | Clearslot suspended the business's API access |
| 503 | api_unavailable | The API is not available for this business |
An address that sends 20 invalid keys within a minute is refused for 15 minutes.