How restrictions work
A scoped key is limited in up to three ways, and every call is checked against each one it carries:- Event occurrences — the key can only act on the occurrences it carries.
- Endpoints — the key can only call the endpoints it carries. Values are stable names such as
registrationStatus, not URL paths, so a key stays valid if a path changes. - Booking form answers — on endpoints that return participants by their answer to a booking form field, the key can only ask for the fields and answers it carries. This one works differently from the other two: a scoped key without any answers can’t call those endpoints at all, rather than asking for any answer.
Out-of-scope calls
A call outside the key’s scope is refused, and the message says why. An occurrence the key does not carry:No thanks with a key granted Opt-in:
403 means the key is working but the call is out of scope; a 401 means the key itself is invalid or has been revoked.
Checking a key’s scope
GET /identity is available to every key, scoped or not, and returns what the calling key can reach:
Managing scoped keys
Scoped keys are created, edited and revoked alongside your other API keys, under Settings → Credentials → Public API in the dashboard. The screen walks you through choosing what a key can do. Two things worth knowing that the screen does not spell out:- Restrictions are part of a key from the moment it is created; there is no window in which it is unrestricted.
- Editing a key’s restrictions does not change its secret. The partner holding the key does not need to do anything, and the new scope applies within a minute — this is how to roll a key over to next year’s edition without re-issuing it. Revoking a key also takes up to a minute to propagate.
Use case: a partner registration check
The most common reason for a scoped key is a partner who needs one answer from you — whether an email is registered for an event — and nothing else. Create a key limited to the occurrences the partner should be able to check and to the registration check itself — the dashboard offers this as a single choice. The partner can check whether an email is registered for those occurrences. They cannot list participants or bookings, read or change event setup, or reach any other part of the API — they see a yes or a no, never participant details. With the key, the partner calls the registration check for one of the chosen occurrences:false rather than an error. Only confirmed places count; matching ignores case and surrounding whitespace. The check is rate limited per key, so a checkout should ask once per customer rather than on every page load. See Check whether an email is registered for the full contract and the exact limits.
Everything else the partner tries — another occurrence, GET /v0/participants even for a chosen occurrence — answers 403 as described above. Participant and booking lists stay with your own unrestricted keys.
Use case: sharing an opt-in audience with a partner
A booking form can ask participants whether they want to hear from a partner — “Tick this box to hear from our official coaching app”. A scoped key lets you hand that partner exactly the people who ticked it, and nobody else. Create a key limited to the occurrences the partner should see, to the form field responses endpoint, and to the field and answer that mean consent. The field is named by the public ID you gave it, and the answer must be one of the options the field offers:?value=No thanks), another field, or GET /v0/participants answers 403. See List participants by their answer to a booking form field for the full contract.
Before sharing, check that the field’s wording promises what the partner will receive. If it says you’ll pass on something this endpoint doesn’t return, or the reverse, change the wording or the arrangement first.
Endpoints that support scoped keys
Every other endpoint answers
403 to a scoped key, including ones that name an occurrence in their URL.