An overview of our API and how to use it
Wazoku’s Open API allows users to integrate with their backend systems and share data back to the Wazoku Platform. The endpoints allow you to send and receive data on a range of content such as ideas, Challenges and users. This document will provide an introduction to the Public API, some example use cases as well as how to get started with authenticating and using the API.
The Public API, as well as a list of all available endpoints, can be accessed here: public-api.wazoku.com
The Open API can be used in various ways to interface with third party or bespoke applications. Below are some examples of use cases we’ve seen with our Open API.
Connecting the Wazoku Platform to an Intranet
The organisation uses a bespoke intranet which acts as a portal through which employees receive news, access software and collaborate with each other. To reduce the number of different software programs employees need to access, the Open API is used to build an integration between the intranet to the Wazoku Platform. Employees can view Challenges, add ideas and stay up to date on innovation programmes directly from the company intranet without needing to navigate to and log into yet another software.
Third Party Identification Number Assignment
Ideas are gathered in a Challenge and progressed through the various stages. At a certain point in the Challenge, once the ideas have been evaluated and the most promising ones have been surfaced, ideas are sent to a third party system via the Open API so that a unique identification number can get assigned to them in this system. The ideas are then sent back to the Wazoku Platform with the updated ID number so all stakeholders can stay informed of progress and of updates to the idea.
Populating Bespoke Dashboards
Organisations have specific metrics and business goals and are often interested in tracking how a successful innovation programme feeds into those metrics. To track these metrics, organisations build dashboards and reporting. Data from the Wazoku Platform such as the number of ideas submitted, the number of ideas implemented, the financial value of ideas and the number of engaged users can be pulled into organisation’s dashboards and reporting tools via the Open API. This allows the organisation to easily track the engagement and value of their innovation workflow and easily present it back to senior stakeholders.
How to Use the Open API
To interface with the Open API, a user will need an API token or an OAuth2 access token.
Each user on the site can have one or more API tokens. The token gives you unlimited access to all the API endpoints on behalf of the user it’s generated for. Site admins on each site can generate API tokens. If you need a new token, please reach out to your site administrator.
Directions for generating an OAuth2 access token are below.
Depending on the data centre your site is hosted on, you will need to use a different URL in your request. These are all of the data centres we currently have as well as their URLs:
For example, if you are on the German data server, your request would look something like this:
curl 'https://public-api-de.wazoku.com/api/v1/challenges' -H 'Authorization: Token <token>:<user_id>'
Filtering and ordering
In most cases, listing endpoints allow you to order the results and filter them. For ordering, use the order parameter. Each endpoint typically accepts at least created and modified. To reverse the order, just put - before it (e.g. -created).
For filtering, lots of options are available. For example, to filter ideas by number of comments, use the num_comments parameter. The format of this parameter looks like this: [min_value]..[max_value]. Either the minimum or maximum value can be omitted.
Updates to the Public API
Prior to February 2021, users had to contact Wazoku to generate an API token for a user. These tokens are supported by versions v3 and earlier of the Public API.
Starting February 2021, we're introducing the capability for site admins to generate tokens directly in the admin panel. These new tokens have a different format and are more scalable and secure. These tokens are compatible with version v4 of the Public API. We recommend all users leverage these new tokens going forward.
The older tokens, as well as v3 and earlier of the Public API, will continue to function normally until 15 August 2021, upon which they will be deprecated. If you are using the older tokens, before this date, we recommend you generate new Public API tokens through the self-service portal in the admin panel and update any integrations that are using the old tokens with your new tokens.
Authentication with the Open API
We support two ways of authentication with our Open API – via API tokens and via OAuth2 access tokens. We recommend you use API keys to build simple internal applications that don't need to access more than a single user's data. We recommend using OAuth2 access tokens if you’re working on more complex applications and want users to easily provide authorization to applications without needing to share private data. You can also more easily handle authorization levels for various end users and tie tokens to different scopes so they can only access data in specific ways.
Generating Public API Tokens as a Site Admin
Site admins can generate API tokens from the admin panel for any of their users.
- Go to the admin panel > Integrations > Public API Tokens
- Enter the email of the user on your platform whom you would like to generate a token for
- Enter a short, memorable name for the token
- Click "Generate"
Once a token has been generated, it will be sent to the specified user as a notification on the platform. The user will only be able to access the token once.
Site admins can also search through all currently active tokens on their platform by user name, email or token name. They can delete any tokens they would like to deactivate (for example, if it is no longer needed or if there is a security concern). To do so, click on the bin icon next to the token and confirm.
Accessing a Generated API Token
If a site admin has generated a token for you, you will receive a platform notification with a link to access the API token.
- Once you click on the link, you will access a page that allows you to copy your new API token.
- The token is hidden by default. You can choose to copy it or to make it visible and manually copy it from this page.
- The token is sensitive – treat it like a password, as anyone who has this token can get access to anything you have access to.
- The token can only be accessed once. If you leave this page and lose access to your token, you will need to contact your site administrator to create a new token for you.
Every user can have one or more API tokens. The token gives you unlimited access to all of the API endpoints on behalf of that user visiting the site.
Here's how it works. Once you obtain an API token, you can send a request like:
curl 'https://public-api.wazoku.com/api/v4/challenges' -H 'Authorization: Token <token value>'
For example, if my token is “thisismytoken”, the request would look something like this:
curl 'https://public-api.wazoku.com/api/v4/challenges' -H 'Authorization: Token thisismytoken'
WARNING: The token should never be used within client-side apps such as mobile, desktop or browser applications. It's only intended for secure server-to-server communication.
Step 1 - App Registration
- Login to the Spotlight domain as a site administrator.
- Register the application at https://<spotlight_domain>/oauth2/applications/register/
- Specify the below parameters when creating a new application -
- Name: App name
- client_type: 'confidential'
- Authorization grant type: 'Authorization code'
- Redirect URI: Where spotlight will redirect after the authentication flow is complete
- A client id and client secret is automatically generated for the app.
- Please note that the registered app will be linked to the spotlight domain used to create the app.
Step 2 - Generate Authorization Code
Spotlight provides OAuth2 support. Once you authenticate and generate a new user token, you can use it to make requests.
- The authorization endpoint is https://<spotlight_domain>/oauth2/authorize/
- Submit a GET request to the authorization end point - https://<spotlight_domain>/oauth2/authorize/?client_id=<client_id>&response_type=code&redirect_uri=<redirect_uri>
- The user needs to follow the authorization flow in the browser.
- Once Spotlight has successfully authenticated the user, a dialog will prompt the user to authorize the app. If the user clicks "Allow", app will be authorized. The OAuth 2 dialog will redirect the user's browser via HTTP 302 to the redirect_uri with an authorization code: http://[:redirect_uri]?code=[:code].
Step 3 - Generate Access Token
- The token endpoint is https://<spotlight_domain>/oauth2/token/.
- Submit a POST request to the token endpoint with the below parameters -
- client_id: <app client id>
- client_secret: <app client secret>
- redirect_uri: <oauth_client_redirect_uri>
- grant_type: 'authorization_code'
- code: <code>
Step 4 - Making requests
The OAuth2 provider issues tokens to users directly, so the token has information about the user. This token can then be stored in user storage (e.g. mobile phone).
Querying content within the communities
curl -X GET "https://public-api.wazoku.com/api/v4/challenges?community_id=8003d8649bdb4a578a6ba45c9ae65ac4&include_descendants=false&order=-created&page=1&page_size=10" -H "accept: application/json" -H "Authorization: Token ***"
If you wish to query content within a community you can use the "community ID" query parameter.
curl -X GET "https://public-api.wazoku.com/api/v4/challenges?community_id=8003d8649bdb4a578a6ba45c9ae65ac4&include_descendants=true&order=-created&page=1&page_size=10" -H "accept: application/json" -H "Authorization: Token ***"
To also include content from nested communities use the query parameter "include descendant".