Authentication
ChronaPilot offers two authentication models. Most integrations need only the first.
Server-side API keys
Use API keys when your server is the one calling ChronaPilot on behalf of your own customers — the classic single-tenant SaaS pattern.
| Prefix | Use | Surface |
|---|---|---|
| pk_live_… | Publishable. Safe in frontend code. | Read-only public endpoints (booking widgets). |
| sk_live_… | Secret. Server-side only. | Full API access for your account. |
| sk_test_… | Sandbox secret. | Identical surface, isolated test data. |
Send the key in the Authorization header as a Bearer token.
curl https://api.chronapilot.com/v1/events \ -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"
Keys are issued and rotated in the dashboard under Developers → API keys. Every key has a name, a creation timestamp, and a "last used" indicator. Rotating a key invalidates the old one immediately — there is no grace period, so script your rotations carefully.
> Never embed an sk_… key in a mobile app, single-page app, or anything a user can decompile. Use the publishable key for client-side flows and proxy mutating calls through your backend.
OAuth — ChronaPilot Connect
When your platform serves multiple end-users who each have their own calendars (multi-tenant OAuth-style), use OAuth. Your platform requests scoped access from a user; ChronaPilot issues a token tied to that user.
- Authorization URL: https://api.chronapilot.com/oauth/authorize
- Token URL: https://api.chronapilot.com/oauth/token
- Flow: OAuth 2.1 with PKCE (no client secret on public clients)
Scopes
| Scope | Grants |
|---|---|
| calendars:read | List calendars and free/busy windows. |
| calendars:write | Mark calendars selected, change colors, change writable. |
| events:read | Read events and event monitoring. |
| events:write | Create, update, cancel events. |
| profile:read | Read the connected user's profile. |
| voice:invoke | Open Voice Realtime sessions on behalf of the user. |
| webhooks:manage | Register and manage webhook endpoints scoped to the connected account. |
Tokens are short-lived (1 hour); refresh with the issued refresh token. The connected_account_id is included in every token payload as cpa_… — pass it with each call to scope the request.
Choosing between API keys and OAuth
- Single-tenant app (a clinic uses ChronaPilot to run its own scheduling): API keys.
- Multi-tenant platform (a CRM offers calendar features to thousands of customers): OAuth + Connect.
Both can coexist. Many platforms use API keys for platform-level operations (analytics, webhook management) and OAuth for per-customer operations.
Errors
| Status | Type | When |
|---|---|---|
| 401 | authentication_failed | Missing or invalid key. |
| 403 | authorization_failed | Key valid, but lacks scope for the operation. |
| 403 | account_deactivated | The end user's ChronaPilot account is deactivated. |
See the full error catalog.