Creating an API Key

Modified on Thu, 18 May, 2023 at 2:00 PM

It’s important to remember that the token is exactly the same as giving someone your email and password. They will have access to act on behalf of you, be careful who you share your token to.

Creating an API key allows you to obtain access to the platform without having to login through the Swift Labs web application. The API key can be used to add and modify athlete and squad information and pull athlete activity data as well as additional administration functions.


Creating the Key

Navigating to your organisation settings and clicking on the last tab within the organisation settings will take you to your API keys for your organisation.



Clicking on the “Add Key” will take you to create a new API Key. To create a new key, three components are required, including; the token name, expiry and token scopes.


By default the token expiry is set to the maximum of three months and must be manually renewed once the token has expired.






Token Scopes

Token scopes restrict the amount of functionality the token has with the account. Selecting the athletes:read token will prevent the token from being able to create or remove an athlete. This gives you fine grain control over the amount of functionality and access the token has. Using the table below, you should determine the level of access required.


Scope
Description
coaches:read
Read coaches for your organisation.
athletes:read 
Read the athletes of your organisation.
athletes:create 
Create athletes for your organisation.
athletes:update
Update athletes for your organisation.
athletes:remove 
Remove athletes for your organisation.
squads:read
Read the squads for your organisation.
squads:create
Create squads for your organisation.
squads:update
Update squads for your organisation.
squads:remove
Remove squads for your organisation.
squads:athletes
List the athletes that are members of the squad.
squads:coaches
List the coaches that are members of the squad
squads:add_coaches
Add coaches to the squad.
squads:add_athletes
Add athletes to the squad.
squads:remove_coaches 
Remove coaches from the squad.
squads:remove_athletes 
Remove athletes from the squad.
activity:read
Read activities of an athlete, acthlete:read also required.
activity:remove 
Remove activities of an athlete, athlete:read also required.
org:read 
Read your organisation details.
org:write 
Update your organisation details.
org:users_read 
Read the users for your organisation.
org:users_update 
Update the users for your organisation.
org:users_remove 
Remove users from your organisation.
user:read 
Read your user profile.
user:write
Update your user profile.


Using your token


Using an application like Postman is an ideal way to test your API key. Appending the token you just generated with the Authorization header, will authorise the requests so long as the token has not expired and has the required scopes.



Authorization: JndHI3iPWR3n6oeMKyOeB1BAs4kbobfchkvakZG9b4sTuSZSr3kjBb3eZA5EjADt3XwP6SGmK0qibs82jIlb3w==




Additional Information


Additional information on the API requests available can be found within our API documentation here. https://swiftperformance.blob.core.windows.net/api/docs/index.html?url=/api/public/SwiftAPI_latest.json

Common errors to look out for:
An invalid token will generate the following error.



{     "Message": "Unable to authorize user."}


A token without the required scope will through this error detailing the required scope for the request.



{     "Message": "Unable to authorize token, could not find scope athletes:read."}


And remember


It’s important to remember that the token is exactly the same as giving someone your email and password. They will have access to act on behalf of you, be careful who you share your token to.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article