An authentication level is the permission tier assigned to an API endpoint: public, user, or administrator. It answers “who may use this operation?” rather than “which credential travels over the wire?” section 8.3 section 8.3.1
Read the tier, then inspect the credential
A checkout endpoint might be marked user because it operates on a shopper’s account. A public slot endpoint allows a logged-out visitor, while an administrator endpoint reserves privileged operations. The credential is a separate question: the user tier might be reached through a session cookie, static API key, or OAuth token, depending on the API surface. section 8.3 section 8.3.1
Use authentication levels to make an API surface legible:
- List every endpoint with its method, path, purpose, and permission tier. section 8.3
- Separate permission from authentication mechanism: public access may require no credential, while user access may use cookies, API keys, or OAuth. section 8.3.1
- Treat the public-versus-internal boundary as a stability promise, not merely a label. section 8.3.1
Table 8.3 Authentication methods for each API surface
|
Mechanism
|
Examples on
Cal.com
|
What it
buys
|
What it
costs
|
|
Session
cookie
|
The booking
page and dashboard (NextAuth, logged-in webapp)
|
Invisible
to the user, refreshes itself, CSRF-protected (blocks forged cross-site
requests)
|
Browser-only;
useless for a server-to-server integration
|
|
None
(public)
|
GET /api/slots for a
logged-out booker
|
Anyone can
read open slots; zero credential friction
|
Must be
rate-limited and bot-gated since it's wide open
|
|
Static API
key
|
The v1 REST
API (?apiKey=cal_live_…)
|
One header,
trivial for scripts and cron jobs
|
Long-lived
secret to store and rotate; full account scope
|
|
OAuth
client
|
The v2 API
for partners embedding Cal.com
|
Scoped,
revocable, per-tenant tokens; users grant access
|
A whole
consent-and-refresh flow to build and operate
|
Compare the credentials commonly attached to different API surfaces, including their integration costs and security trade-offs. section 8.3.1
