Skip to Content

Authentication and scopes

Secret keys for your server, scopes per key, and the public surface that needs no key.

Base URL: https://api.whocoming.com. JSON in and out, snake_case field names. The OpenAPI 3.1 document is at /v1/openapi.json, and every endpoint is in the API reference.

Secret keys

Send your key as a bearer token:

curl https://api.whocoming.com/v1/events \
  -H "Authorization: Bearer wc_test_..."
  • wc_live_... keys work on live data. wc_test_... keys work on test data.
  • Create and revoke keys in the dashboard. A key is shown once, when you create it; we store only a hash.
  • Keys belong on your server. Never put one in browser code, a mobile app, or a NEXT_PUBLIC_ variable.

A missing, malformed, unknown or revoked key answers 401 unauthorized.

Scopes

Each key carries a set of scopes. A call outside them answers 403 insufficient_scope.

ScopeAllows
events:readList and read events and series.
events:writeCreate, update, cancel and delete events and series.
rsvps:readList and read RSVPs. Export a guest's data.
rsvps:writeCreate, update, check in and delete RSVPs. Erase a guest.
webhooks:writeManage webhook endpoints, read the delivery log, redeliver.

GET /v1/usage works with any key. Give each integration the smallest set it needs: a check-in app needs only rsvps:read and rsvps:write.

The public surface

Routes under /v1/public need no key. They expose only what a guest may see or do, allow requests from any website (CORS), and are what the widget uses:

EndpointDoes
GET /v1/public/events/{id}Event details, form fields and counts. No guest data.
POST /v1/public/events/{id}/rsvpsRSVP as a guest. Needs a Turnstile token.
GET, PATCH /v1/public/rsvps/{manage_token}A guest views, changes or cancels their own RSVP.
GET /v1/public/orgs/{slug}/eventsUpcoming public events, for a calendar.
GET /v1/public/events/{id}/calendar.icsThe event as a calendar file.
POST /v1/sandboxA 24-hour test organization, for trying the API.

Public RSVPs are limited to 5 a minute and 30 an hour per IP address per event. If your organization set allowed websites in the dashboard, a public RSVP from any other origin answers 403 origin_not_allowed.

Private events are never served on the public surface.

On this page