Scoped API keys - Let's Do This

An API key normally has access to everything in your organization. When a partner — a sponsor validating a discount at their checkout, a timing provider, a supplier — only needs one answer from you, you can give them a key that can get that answer and nothing else. A scoped key can check whether an email is registered for the event occurrences you choose. It cannot list participants or bookings, read or change event setup, or reach any other part of the API. The partner sees a yes or a no; they never see participant details.

Creating a scoped key

In the dashboard, go to Settings → Credentials → Public API and choose Create new key. Under What can this key do? choose Only check registrations for specific events, then add every occurrence the partner should be able to check — the event, then the edition. Restrictions are part of the key from the moment it is minted: there is no window in which it is unrestricted. The key itself looks and behaves like any other API key — same header, same base URLs.

Changing which occurrences a key can check

Open the key’s menu in Settings → Credentials → Public API and choose Edit restrictions. Add or remove occurrences and save; the secret does not change, so the partner holding the key does not need to do anything. The new scope applies within a minute. This is how to roll a partner’s key over to next year’s edition without re-issuing it. The same screen lets you switch the key to Everything in your organization, which removes its restrictions entirely. Revoking a key also takes up to a minute to propagate.

What the partner can call

With the key, the partner calls the registration check for one of the chosen occurrences:

curl --request POST \
  --url "https://api.letsdothis.com/v0/event-occurrences/12345678901/registration-status" \
  --header "Authorization: Bearer PARTNER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "email": "runner@example.com" }'

{ "eventOccurrenceId": "12345678901", "registered": true }

An email that is not registered answers false rather than an error. Matching ignores case and surrounding whitespace. See Check whether an email is registered for the full contract.

What the partner gets everywhere else

Any call outside the key’s scope is refused before any data is read, and the message says why. An occurrence you did not choose:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key is not permitted to access event occurrence 12345678902"
}

Any other endpoint — including GET /v0/participants, even for a chosen occurrence:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key is not permitted to call this endpoint"
}

A 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. Participant and booking lists stay with your own unrestricted keys.

Checking a key’s scope

GET /identity is always available to a scoped key and returns what it can reach:

curl --request GET \
  --url "https://api.letsdothis.com/identity" \
  --header "Authorization: Bearer PARTNER_API_KEY"

{
  "organiserId": "81274",
  "eventOccurrenceIds": ["12345678901"],
  "endpoints": ["registrationStatus"]
}

This is the stored shape of a scoped key: the occurrences you chose, and the registration check as the one endpoint it may call. The endpoints values are stable names rather than URLs, so a key stays valid if an endpoint’s path changes.

Under the hood

Restrictions are stored as two independent lists — event occurrences and endpoints — and each is enforced on its own. A key can carry either or both:

Both lists — the dashboard’s Only check registrations for specific events option. The key can call the registration check, for the chosen occurrences only.
Endpoints only — the key can call the listed endpoints for any occurrence in your organization. With registrationStatus alone, that is a registration check across every event you run.
Occurrences only — the key can call every occurrence-scoped endpoint, but only for the chosen occurrences. Today that is the registration check; as more occurrence-scoped endpoints are opened up, such a key reaches them automatically. Endpoints that are opened to scoped keys without being tied to an occurrence stay off-limits to it.

Keys created through GraphQL, or before the dashboard option existed, may carry one list without the other; the dashboard shows those as Custom restrictions and lets you edit each list directly. Every endpoint that supports scoped keys says so on its own page. Others — including ones that name an occurrence in their URL — are reserved for unrestricted keys and answer 403 to a scoped one.

​Creating a scoped key

​Changing which occurrences a key can check

​What the partner can call

​What the partner gets everywhere else

​Checking a key’s scope

​Under the hood