Getting started
Authentication
Every request is authenticated with a secret API key sent in a header. Each key carries only the permissions (scopes) you give it.
Sending your key
Send the key as a bearer token. x-api-key: <key> also works. Keys in the URL are rejected, because URLs end up in logs and browser history.
Header
curl https://calendeur.com/api/v1/me \
-H "Authorization: Bearer mcp_live_..."Scopes
Give each integration only what it needs. A key used for reporting can't book or cancel meetings, and an AI agent only sees the tools its key allows.
| Scope | Allows |
|---|---|
read:bookings | List event types, availability and bookings |
execute:bookings | Create, reschedule and cancel bookings; add meeting notes |
read:contacts | List and read contacts |
write:contacts | Create and update contacts |
read:routing | List routing forms |
execute:routing | Submit routing forms |
manage:webhooks | Create and delete webhook subscriptions |
read:analytics | Read analytics |
execute:voice_calls | Place AI voice calls |
A request without the right scope gets 403 insufficient_scope.
How keys are protected
- Keys are shown once, when created. Calendeur stores only a SHA-256 hash, so a key can't be recovered later, even by us.
- Revoking a key in Settings ends its access immediately, including open MCP sessions.
- Each key is rate limited separately, so one integration can't exhaust another's quota.
- Every key can read and change only its own account's data.
- All traffic is HTTPS.
Good practice
Never ship a key to a browser or app
Anyone who can see a key can use it. Call the API from your server, store keys in a secrets manager (AWS Secrets Manager, Vercel or Doppler environment variables) and never commit them to git.- Use one key per integration and environment, named so you can tell them apart.
- Rotate a key by creating the new one, deploying it, then revoking the old one.
- Check Last used in Settings → API keys and revoke keys you don't recognise.