Authenticate with the PitPath Chrono API

Every request to the PitPath Chrono API must include a valid API key. Keys are sent in the X-API-Key HTTP header and are scoped to a role that controls what operations the caller can perform.

How API key authentication works

When you make a request, Chrono reads the X-API-Key header, looks up the matching key, and checks whether the associated role permits the requested operation. There are no session cookies, no OAuth flows, and no bearer tokens — just the key in the header.

X-API-Key: chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are stored as hashed values. Once a key is created, the plain-text token is returned only once in the creation response. If you lose it, you must create a new key and revoke the old one.

Always store API keys in a secrets manager or environment variable. Never hard-code them in source code or check them into version control.

Getting an API key

Your first ADMIN key is provisioned when your license is created by the PitPath team. To create additional keys, use the API keys endpoint with a key that has at least CR role.

curl
fetch

curl --request POST \
  --url https://your-chrono-host/api/v1/api-keys \
  --header "X-API-Key: chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Timing software integration",
    "role": "CR"
  }'

const response = await fetch('https://your-chrono-host/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'X-API-Key': 'chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Timing software integration',
    role: 'CR',
  }),
});

const data = await response.json();
console.log(data.token); // save this — it won't be shown again

The response contains the key metadata and the one-time plain-text token:

Example response

{
  "apiKey": {
    "id": "k3y4a5b6-0000-0000-0000-000000000030",
    "licenseId": "a1b2c3d4-0000-0000-0000-000000000000",
    "name": "Timing software integration",
    "keyPrefix": "chrono_cr_",
    "role": "CR",
    "enabled": true,
    "lastUsedAt": null,
    "createdAt": "2025-01-15T09:00:00Z",
    "updatedAt": "2025-01-15T09:00:00Z"
  },
  "token": "chrono_cr_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
}

The name field must be between 3 and 120 characters. Use a descriptive name so you can identify the key’s purpose when listing all keys later.

Roles

Every API key has exactly one role. Roles are cumulative — a higher role includes all permissions of lower roles.

Role	Level	What it can do
`R`	0	Read any resource (events, laps, rigs, participants, tracks, cars, etc.)
`CR`	1	Everything in `R`, plus create new resources and create additional API keys
`CRUD`	2	Everything in `CR`, plus update and delete resources
`ADMIN`	3	Everything in `CRUD`, plus license management and assigning any role to keys

Choosing the right role

Use R for dashboards, public leaderboards, or any integration that only needs to display data.
Use CR for sim rigs. When Chrono registers a rig, it auto-generates a CR key for that rig to submit laps.
Use CRUD for your primary results management software that needs to correct or delete records.
Use ADMIN only for your back-office tools that manage the license itself or provision other ADMIN keys.

A key can only assign roles up to its own level. An CRUD key cannot create an ADMIN key. Only ADMIN keys can assign any role freely.

Using a key in a request

Include the key in every request via the X-API-Key header. There is no separate login step.

curl
fetch

curl --request GET \
  --url https://your-chrono-host/api/v1/events \
  --header "X-API-Key: chrono_cr_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"

const response = await fetch('https://your-chrono-host/api/v1/events', {
  headers: {
    'X-API-Key': process.env.CHRONO_API_KEY,
  },
});

const events = await response.json();

Listing your API keys

To see all keys associated with your license, use a key with at least CR role:

curl
fetch

curl --request GET \
  --url https://your-chrono-host/api/v1/api-keys \
  --header "X-API-Key: chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://your-chrono-host/api/v1/api-keys', {
  headers: {
    'X-API-Key': process.env.CHRONO_API_KEY,
  },
});

const keys = await response.json();

The response is an array of key objects. Note that keyPrefix is returned (e.g. chrono_cr_) but the full token is never exposed after initial creation.

Rotating a key

To rotate a key, create a new one with the desired role, deploy it to your application, then revoke the old key. There is no in-place secret rotation — the token value is fixed at creation. Step 1 — Create the replacement key:

curl

curl --request POST \
  --url https://your-chrono-host/api/v1/api-keys \
  --header "X-API-Key: chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Timing software integration v2",
    "role": "CR"
  }'

Step 2 — Update your application to use the new token, then revoke the old key:

curl

curl --request DELETE \
  --url https://your-chrono-host/api/v1/api-keys/k3y4a5b6-0000-0000-0000-000000000030 \
  --header "X-API-Key: chrono_adm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A successful revocation returns 204 No Content.

Revocation is immediate and permanent. Make sure the new key is deployed and working before you delete the old one.

Common authentication errors

Status	Meaning	What to do
`401 Unauthorized`	The `X-API-Key` header is missing, the token is invalid, or the key has been revoked.	Check that the header is present and the token matches the one returned at creation.
`403 Forbidden`	The key’s role does not permit the requested operation.	Use a key with a higher role, or request that an ADMIN create one for you.

If you receive a 401 on a key you believe is valid, check the enabled field by listing your keys. A key can be disabled via PATCH /api/v1/api-keys/{apiKeyId} without being fully revoked.

Get Started

Core Concepts

Guides

Configuration

Authenticate with the PitPath Chrono API

How API key authentication works

Getting an API key

Roles

Choosing the right role

Using a key in a request

Listing your API keys

Rotating a key

Common authentication errors

​How API key authentication works

​Getting an API key

​Roles

​Choosing the right role

​Using a key in a request

​Listing your API keys

​Rotating a key

​Common authentication errors

How API key authentication works

Getting an API key

Roles

Choosing the right role

Using a key in a request

Listing your API keys

Rotating a key

Common authentication errors