Skip to content

Authentication

Every request to the RaceRanger API must include a Bearer token in the Authorization header.

Authorization: Bearer rr_o_4f8c...

API keys are minted from inside the RaceRanger app by an organisation admin (or, for an event-scoped key, anyone who can edit the event). The API itself does not expose a key-creation endpoint — provisioning happens in-app to keep the audit trail tied to a real user.

Key tiers

There are two tiers, distinguished by their prefix.

Prefix Tier What it can do
rr_o_ Org-scoped Bound to one organisation. Can list every event under the org, read and (with the right scopes) write events, races, and athletes, and manage webhooks.
rr_e_ Event-scoped Bound to one event. Read-only. Cannot be granted write scopes, and can't list events — it reads its event with GET /v1/events/{eventId}.

Event-scoped keys are the right choice for handing limited access to a race organiser, a timing partner, or a media display. Org-scoped keys are for first-party integrations that need to manage data across multiple events.

Scopes

Each key carries an explicit list of scopes. Requests that need a scope the key does not hold return 403.

Scope Allows
read:events List and read events.
read:races List and read races.
read:athletes List athletes in a race.
read:penalties List penalties in a race (status approved or served).
read:incidents List incidents in a race.
write:events Create and update events. Org keys only.
write:races Create and update races. Some race fields lock once the race starts. Org keys only.
write:athletes Bulk-import athletes into a race. Org keys only.
manage:webhooks List, create, update, and delete webhook subscriptions, rotate their secrets and read their deliveries. Org keys only.

Event-scoped keys can only hold read:* scopes.

Minting a key

In the RaceRanger web app:

Org-scoped key (rr_o_…):

  1. Sign in as an organisation admin.
  2. Top nav → Organizations.
  3. On your organisation's card (left sidebar), click Edit organization → API keys tab.
  4. + New key → fill in Name, Scopes, optional Restrict to event IDs, Expires in (days) → Create. The events you restrict a key to must belong to your organisation.

Event-scoped key (rr_e_…, read-only):

  1. Open an event → Edit Event → API keys tab. Anyone who can edit the event can create these.
  2. Create-key flow is the same, with the scope picker limited to read:*.

Both API keys tabs appear once RaceRanger has switched on API access for your organisation.

In both cases the plaintext key is shown once in the "API key created" dialog. Copy it into your secret store immediately — RaceRanger does not store the plaintext and cannot show it again. If you lose it, revoke the key and mint a new one.

Rotating and revoking

Each key has an expiry date (default 365 days, hard-capped at 730). The API keys tab warns you when a key expires within 30 days. You can rotate or revoke a key at any time from the same tab:

  • Rotate mints a new key with the same scopes and event restriction and shows it once. The old key keeps working for 30 days, then expires — time to move your integration over.
  • Revoke stops a key within about 10 seconds. Revoked keys can't be reactivated.

A revoked or expired key gets 401. The Quickstart walks through the full flow.

Resource access rules

A key only sees the resources it owns:

  • Org keys see every event under their organisation. If an org key is restricted to specific events at creation time, it only sees those.
  • Event keys only see their one event.

A request for an event outside the key's scope returns 403. If RaceRanger switches API access off for your organisation, every request made with its keys returns 403 as well.