Create a key
Create an API key in the app: its name, its scopes, the terms of use, and the only time you can copy it.
A key is the password of a tool. You create one per tool, with only the rights that tool needs. Everything happens in the app.
1. Open the API keys page
In the app, go to Settings › Integrations › API keys. Click New key, or Create my first key if the list is empty. If your plan does not include the API, the page explains it instead of the list.
2. Name the key
Use the name of the tool that will use it, for example "Nightly sync". The name helps you recognize the key in the list and in the Call log.
3. Choose what the key can do
You tick scopes, grouped by family of data: Students, Training, Check-ins, Habits and the others. Each family offers up to three boxes: Read, Write and Delete. Ticking Delete ticks Write for you. By default, Read is ticked on Students, Training, Check-ins and Habits.
The bottom of the window shows the mode of the key. It is a label that follows the strongest permission you ticked:
| Mode | Shown when |
|---|---|
| Read | you only ticked Read boxes |
| Write | at least one Write box is ticked, and no Delete box |
| Full | at least one Delete box is ticked |
The mode adds no read access. A key with only Write on Students shows Write and cannot read students: tick Read too when the tool has to read.
Further down, the Sensitive data section groups student contact details, form answers, the health part of the initial check-in and media. Tick only what the tool really needs. Without Student contact details, the email and the phone of a student are missing from the responses.
4. Accept the terms of use
A Terms step appears before your very first key. It also appears before a key that can write, if you have not yet accepted the current version. Keep three points in mind:
- a key that can write acts in your name with your students;
- you remain responsible for the tools you connect;
- calls are logged (key, route, date, status), and you find them in the Call log.
The log lists the calls that reach the credit step. GET /me and the refusals that fall before it, such as a 401, a 403 or a 429, leave no row.
Tick the acceptance box to continue.
5. Copy the key
Click Create the key. A window shows the full key, which starts with fd_live_. Copy it with the Copy button and paste it into your tool. The window also offers a free first call, which you will find in First call.
The key is shown only once
Fit'Distance does not store the full key: once the window is closed, it is never shown again. Treat it like a password. Do not put it in a client-side application or in a public repository. If you lose it, revoke it and create a new one.
Five active keys at most
You can have five active keys at the same time. To create a sixth, revoke one of the five first: the app asks you to. Revoked keys no longer count.
Rename, revoke, change the scopes
- Rename: the name can be changed in the list, the key stays the same.
- Revoke: a revoked key stops working, and its calls get a 401.
- Change the scopes: a key cannot be edited. Create a new one with the right scopes, put it in your tool, then revoke the old one.
If a call gets a 403 SCOPE_MISSING, details.scope names the missing scope: that is the one to tick on the new key.