API keys and the API reference

An API key lets your timing company, or your own system, send results straight to Breaktape for one of your races. Each key belongs to your organisation, can only do what you allow, and can be switched off in a second if it's lost.

Make a key

Only admins can make or revoke keys.

1. Go to Settings, then API.
2. Under Make a key, fill in Who it's for. Usually that's your timing company, like "Northline Timing". One key per company makes it easy to revoke later.
3. Under What it can do, tick Send results. It's the only permission at the moment, and it lets the key send results for your races.
4. Press Make key.
5. Your new key appears at the top of the page. Press Copy key and send it to them securely, for example through a password manager they use, not in a plain email.

The key is shown once. You'll see "It won't be shown again: if it's lost, revoke it and make another." We don't keep a copy we can show you.

Give them the race ids

Results are sent for one race at a time. The Race ids table on the same page lists every race, whether its results come Live or by File, and its id with a Copy button. Send your timing company the id for each race they're timing.

See your keys

Under Keys, each key shows:

• the name you gave it
• the first few characters, like bt_live_k7Hq2m9P..., so you can tell keys apart
• when it was made and when it was last used, or "Not used yet"
• what it can do

Revoke a key

Revoke a key when a timing contract ends, or if a key might have been seen by someone it shouldn't have.

1. Press Revoke next to the key.
2. Press Yes, revoke it to confirm, or Keep it to go back.

It stops working straight away. Revoked keys are listed by name under the Keys list, so you keep a record. If the company still needs access, make them a new key.

The API reference

The full reference for developers is at app.breaktape.com/developers. There's a Read the API reference link at the top of Settings, then API. It covers:

• how to send results, with an example
• every field a result can carry, including the required isFinal flag: true once the timing is official, false while it's provisional
• the responses and error messages
• good practice for race day

Only results marked final ever become medals. Developers with questions can contact support@breaktape.com.

Good to know

• Keys belong to your organisation, not to a person. Removing someone from your team doesn't revoke keys they made.
• Keys should stay on a server. The reference asks developers never to put a key in a web page or app.
• Sending results isn't the same as releasing medals. Nothing reaches a finisher until someone on your team approves it. See Live races: approving the first medals.
• If your account is on hold, you can't make or revoke keys until it's sorted.

Related guides

• Sending live results
• Live races: approving the first medals
• Your team and their roles