The GraphQL API is a secure, read-only window into the data your organisation stores in QUOODA®.
This gives you the ability to connect the information held within QUOODA® to other business systems or data reporting tools. You can also build data exports using this API to extract data from the system for a variety of business reasons.
The read-only nature of the API means that it can only be used to extract data from QUOODA®. It cannot be used to create, update, or delete records within QUOODA®.
What does your business need before you can use the GraphQL API?
Using the QUOODA® API requires in-house technical expertise. You will need a suitably skilled team member to build and manage your queries and integrations — such as a BI report builder, data analyst, or integration engineer.
QUOODA® Support can assist with enabling the feature, but does not provide consultancy for building queries, reports or integrations.
Enabling the feature
The GraphQL API is not enabled automatically. If this is something your organisation would like to utilise, a Super User needs to contact the QUOODA® Support Team. To enable the API, the following will be needed:
- Additional terms will need to be agreed to and signed by the appropriate person within your business to cover the data security considerations of using an API.
- A small (out-of-hours) period of downtime would need to be arranged to onboard your data and make the feature available to you.
Setting up Security
This is a very important step in this process. In this step, you decide who will have access to the Graph API key within your business. That key provides access to the data exposed through the GraphQL API configuration. We recommend limiting this to the minimum number of people who are absolutely essential.
Security access is controlled via Role Security, so if you enable it for a role, everyone with that role will be able to access and refresh the key. For this reason, it would be worth considering creating a new role specifically for this elevated access. For example:
- You may want to create a specific role for the data engineer who would be using the API to access the system and manage the key.
- Or, if a Super User is going to manage the key, rather than giving access to everyone with a ‘Super User’ role, you could create a ‘Super User API’ role with all the normal Super User access, plus this extra feature.
Once you have decided which role(s) will have access, you can amend the Role Security ‘Company Configuration - GraphQL API Key’ feature to give those rules ‘Read’ and/or ‘Edit’ access to this area.
- Read – Users with that role will be able to read and copy the key for use
- Edit – Users with that role will be able to generate the API Key
IMPORTANT - Downstream access control is your responsibility
The security framework you have created within QUOODA® through the various options at your disposal would only be enforced for logged-in users within the QUOODA® Portal and Mobile App.
Data consumed through the GraphQL API is accessed outside the QUOODA® Portal and Mobile App, so any access controls applied within downstream systems are the responsibility of your organisation.
API Endpoint
The endpoint is a specific web address that serves as the entry point for communicating with the API. Any external application or integration that needs to exchange data with Quooda does so by directing its requests to https://graph-api.quooda.com/.
Generate an API Key
The users with a role that has access to ‘Edit’ will be able to generate the API key, which is the access token needed to access the data via the endpoint.
Step 1. Go to the Graph API Key screen
You can access this via ‘Settings > Configuration > Company Configuration’ within the main QUOODA® Menu. From there, you can click on the ‘Graph API Key’ tab.
Step 2. Generate a key
If the API is not yet in use, the fields here will be blank. If a key has already been generated, you will be able to see that key and the date and time it was generated.
- Click Generate Key
- Read the confirmation - this explains that the newly generated key will be immediately usable. If an existing key is in place, this will expire in 7 days, giving you time to update the key on any existing queries, reports, and integrations.
- Click ‘Generate’ to continue, or ‘Cancel’ to exit without generating a new key.
Step 3. Copy the key for use
You can use the ‘Copy’ button within the Key field to copy the API Key for use in the external tool(s) you are building your connections to the data with.
Please note: You can repeat these steps to regenerate the key at any time. We recommend regenerating keys periodically to ensure your data security, just as you would with any password. We would also recommend regenerating when anyone who has access to this key leaves the business to ensure that they cannot access your data after they have left. If you have any concerns about the security of your key, please contact support.