Skip to main content

API Keys

Pro plan. API access requires a Pro plan. View plans.

API keys authenticate requests to the CalendarPipe REST API and to CalDAV. Every key belongs to your account, and each key carries the scopes you picked for it.

Create a key​

  1. Open API in the CalendarPipe sidebar.
  2. Enter a name in Generate New Key (for example, Production server).
  3. Choose the scopes the key needs. All scopes are selected by default — clear the ones the integration will not use.
  4. Click Generate.
  5. Copy the key immediately. CalendarPipe shows the full key once and stores only its hash — there is no way to retrieve it later.

Keys look like this:

cp_8f3a1c4e9b7d2f6a5c8e1b4d7f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4

The first eight characters (cp_8f3a1c) are the prefix. CalendarPipe lists the prefix on the API page so you can identify keys later, but the full key is never shown again.

Authenticate a request​

Pass the key in the Authorization header:

GET /api/v1/hosted-calendars
Authorization: Bearer cp_8f3a1c4e9b7d2f6a5c8e1b4d7f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4

For CalDAV, use the key as the password — see CalDAV Setup. A CalDAV client browses calendars and writes events, so give the key hosted-calendars:read, events:read and events:write.

Scopes​

A key can only call the operations its scopes cover. Every request outside them is refused, whatever the account behind the key is allowed to do.

ScopeGrants
calendars:readList connected calendar accounts and their calendars.
events:readRead events from any connected calendar.
events:writeCreate, update and delete events, and send or cancel invitations.
hosted-calendars:readRead hosted calendars and their settings.
hosted-calendars:writeCreate, update and delete hosted calendars, rotate their tokens, and manage webhooks.
invitations:readList invitations a hosted calendar has received.
invitations:writeRespond to an invitation. Accepting one adds its event to the calendar.
sync-rules:readRead sync rules and dry-run a gate function against them.
sync-rules:writeCreate, update, delete and force a re-sync of sync rules.

The scope each operation needs is published in the OpenAPI description under the operation's security entry, so a client generator can request the right key without reading this page.

A key that authenticates but lacks the scope gets 403 Forbidden:

{
  "error": "Forbidden",
  "code": "insufficient_scope",
  "message": "This API key is missing the \"events:write\" scope.",
  "details": {
    "required_scope": "events:write",
    "documentation": "https://docs.calendarpipe.com/developers/api-keys"
  }
}

The response also carries WWW-Authenticate: Bearer error="insufficient_scope", scope="events:write". See Errors for the envelope and the full list of code values.

Scopes cannot be changed after a key is created — generate a new key with the scopes you want and revoke the old one.

POST /api/v1/sync-rules/dry-run needs both sync-rules:read and events:read: it changes nothing, but its result contains events read from the rule's source calendar.

Invitations are their own resource rather than part of hosted-calendars, so an agent whose only job is to accept meetings can hold invitations:read and invitations:write and nothing else — in particular not the scope that deletes calendars and rotates feed tokens. Responding does not additionally need events:write: the event an acceptance creates comes from the invitation the organiser sent, not from the caller.

Keys created before scopes existed carry all of them, so nothing that worked before stopped working.

Lifetime​

  • Keys do not expire automatically. They remain valid until you revoke them.
  • The Last Used column on the API page shows the most recent successful authentication, useful for spotting unused keys.
  • CalDAV uses the key as a Basic Auth password and charges each method what the equivalent REST call costs: browsing (PROPFIND, REPORT, GET) needs hosted-calendars:read and events:read, and writing an event (PUT, DELETE) needs events:write. A key narrowed below that gets 403 from the CalDAV endpoint — see CalDAV Setup.

Revoke a key​

On the API page, click Revoke next to the key. Revocation is immediate — subsequent requests with that key receive 401 Unauthorized. Revocation cannot be undone; generate a new key to restore access.

Storage and rotation​

  • Treat keys like passwords. Store them in your secrets manager (1Password, AWS Secrets Manager, Vercel environment variables) and never commit them to source control.
  • Rotate by generating a new key, deploying it, then revoking the old one. Old and new keys can coexist during the cutover.
  • If a key is exposed (committed to a public repo, posted in a screenshot, leaked in logs), revoke it immediately and generate a replacement.

Event list limits​

GET /api/v1/events and GET /api/v1/calendars/{id}/events return at most 2500 events per calendar for the requested start/end window (before your offset/limit page). When that cap is hit, the response includes meta.truncated: true and keeps meta.has_more true on the last page so you can tell the window is incomplete — narrow the date range to continue.

  • Errors — status codes returned when authentication or a scope check fails.
  • CalDAV Setup — using an API key with CalDAV clients.
  • API Reference — the interactive REST reference.
Last updated on