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. 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.

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 (pre-start only). Org keys only.
write:athletes Bulk-import athletes into a race. Org keys only.
manage:webhooks Create, update, and delete webhook subscriptions. 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.

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

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

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.

Each key has an expiry date (default 365 days, hard-capped at 730). You can rotate or revoke a key at any time from the same tab. The Quickstart walks through the full flow with screenshots.

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.

Passing a path that names a different event returns 403, not 404, to avoid leaking the existence of resources outside the key's scope.