- Creating unique API credentials
- Editing or revoking an API token
- Your API credentials list
- Testing your API credentials using Postman
- Rate limiting
- Spark API documentation
- Related articles
Spark features a comprehensive Application Programming Interface (API) to allow third-party systems to query and manipulate its data. Security and confidentiality is of the upmost importance when working with system data and all requests to the Spark API must be authenticated.
Creating unique API credentials
Spark allows you to generate your own unique token which can be used to authorise your access to the API. Begin by navigating to the API credentials option in the Settings for the LMS.
If this is the first time API credentials are being set up then you should see a button titled "Create new API credentials".
This is where you can create your new API token and assign the required permissions to that token. E.g. will you require your token to provide you with full access to all organisational units on the LMS, or do you only require access to specific units?
API token name
Give your API credentials a name in the Account box. This might be the name of a client or a project.
Note: A number of different API tokens can be created with unique assigned permissions so it is important to give each token a name which clearly and accurately communicates its use.
API token permissions
You can decide what kind of permissions you want to link to your API Token with the following options:
Access to - allows you to choose between giving your credentials access to LMS data across all organisational units or only data belonging to specific units within the organisational structure.
If you require your API credentials to have access to a specific organisational unit only, select Data belonging to specific organisational units... in the drop down menu to access a pop-up where you will be able to navigate through the organisation structure down to the level of your choice and use the check boxes to make your selections. Check the box of the unit(s) you require access to and then select Done.
There are also four other types of permission that can be enabled to customise the access assigned to your credentials:
Distribution - Will let you distribute courses to Spark users.
Training items - Will allow you to choose if you want the ability to maintain document and module content via the API, e.g. adding or amending these items.
Users - Will give you access to maintain various levels of user via the API. You might want to add these permissions if you intend to add users or update their user type.
Advanced - Include these permissions if you intend to maintain your company structure or job role definitions. These permissions will be essential if you want to adjust company structure or add/edit your role definition list via the API.
Note: Security is of the upmost importance when using an API to query data so by making sure that your token permissions are as specific to your requirements as they can be, you will be ensuring that access to the API isn't opened any further than is needed.
Editing or revoking an API token
When you have assigned a name and your required permissions, select "Create API credentials" and you will be sent to a page where your token is displayed in the Security token tab. Accessing the Edit tab will allow you to adjust the name and the permissions that you originally assigned above.
If you want to delete a token that is no longer in use then select the "Revoke token..." button.
Note: This will PERMANENTLY revoke access to the token and cannot be undone.
Your API credentials list
Navigating back a level in the system, you should now see that an API credentials list has been created and that your new token is present. Each item on this list displays your token name, the partially hidden token identifier, and the organisational unit access that is currently assigned to your token.
Note: Revoking a token will not remove your API credentials from this list entirely. It will only remove the token assigned to your credential item and all API access associated with that token.
Testing your API credentials using Postman
At this point, it is recommended that you test your newly generated credentials to ensure that you are able to access the Spark API by sending a basic request to receive some data using a GET request.
Postman is a free API collaboration platform that will allow you to set up requests to an endpoint of your choice using your API token for authorisation.
Note: You can download and learn more about the Postman desktop application by visiting the link provided in the Related articles section at the bottom of this page.
Creating a new collection and request
In your Postman workspace select "New Collection" and give your collection a title relating to your testing activity e.g. "Spark API". Right click on your collection from the Collections list and select "Add Request".
You can give your request a name which reflects what you are going to query and then add an optional description.
Note: If the API has supporting documentation, it's a good idea to link to the area in this resource that relates to the endpoint you want to access. Use square brackets to denote what the link navigates to and parentheses to contain the url.
You can also assign this request to a collection or a folder within a collection. Then select "Save to *your collection/folder name*".
Assigning your API token
Postman allows you to add an authorisation method at a collection or request level. So if you have a single API token which you want to use to authorise a number of different requests, you can assign it to an authorisation method at the collection level and the authorisation will cascade to all requests within that collection.
Right click on your collection in the Collections list and select "Edit". Click the "Authorization" tab in the settings editor and select "API Key" from the TYPE drop-down menu.
Give your Key a name and paste the API token that you were assigned on Spark in to the Value box. This value should be presented as follows - 'token *********************************' with the asterisked line replaced with your generated token.
Finally we want to add these authorisation details as a new parameter in the request header and select "Update" to save your authorisation method.
Note: It's good practice to keep your API token as secure as possible at all times. You can assign your API token to a variable in the "Variables" tab and reference the variable name instead of explicitly displaying your API credentials.
Querying the API endpoint
Ensure that the request method is set to GET using the method drop-down list and enter the url of the endpoint you wish to query at the top of your workspace.
Then select the "Authorization" tab below the url input box and ensure that TYPE is set to 'Inherit auth from parent'. This will mean that your API key is added to the authentication header of your request.
Now select the "Send" button to the right of the url input box and Postman will process your request.
If your request has been successful you should observe a 200 OK Status and some data as body content at the bottom of your Postman workspace. This will be the data requested from the API endpoint you queried, presented in a JavaScript Object Notation (JSON) format.
Note: if you receive a 401 UNAUTHORIZED Status this means that your authorisation hasn't been set up correctly. You can try the following steps to troubleshoot:
- Ensure that you have entered your API token correctly from the Spark LMS;
- Check to make sure authorisation type is set to API Key and that this parameter is getting added to your request header in your collection authorisation settings;
- Make sure that the authorisation header is being inherited from your collection settings.
Rate limiting
The Spark API will throttle large numbers of requests made over a short period of time to ensure the system is protected from overload or abuse. This will result in a 429 TOO MANY REQUESTS Status response, which includes a Retry-After header indicating how long in seconds before a new request will be accepted by the API.
Spark API documentation
The Spark API has been thoroughly documented and this resource can be accessed by selecting "API documentation" at the top of the API Credentials page.
This documentation provides detailed information for using the API to make queries to Spark, including a full list of available endpoints, using your API token to assign correct authorisation to your requests, REST methods accepted by the API, and supported data formats.
Related Articles:
Download and learn how to use the Postman API collaboration platform here.