Public API

The Wazoku Public API lets you integrate with your backend systems and share data between the Wazoku Platform. You can use the endpoints 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, how to get started with authenticating and using the Public API, and some example use cases.

You can find the full list of available endpoints here: public-api.wazoku.com

Use cases

The Public 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 Public API.

Connecting the Wazoku Platform to an intranet

The organization 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 Public 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 programs 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 surfaced, ideas are sent to a third-party system via the Public 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

Organizations have specific metrics and business goals and are often interested in tracking how a successful innovation program feeds into those metrics. To track these metrics, organizations 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 the organization’s dashboards and reporting tools via the Public API. This allows the organization to easily track the engagement and value of their innovation workflow and easily present it back to senior stakeholders.

How to use the Public API

To interface with the Public API, you 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.

Data centers

Depending on the data center your site is hosted on, you will need to use a different URL in your request. These are all of the data centers 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 the 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 in 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 Public API

We support two ways of authentication with our Public 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.

1. Go to your platform home page.

2. Select Settings > Admin Panel > Integrations > Public API Tokens.

3. Enter the email address of the user you want to generate an API Token for.

4. Enter a short, memorable name for the token.

5. 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.

1. Check your inbox for access email.

2. Click the link in the email.

3. Copy your API Token.

Request Format

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 such as:

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'

OAuth2 Authorisation

Step 1 - App Registration

1. Login to the Spotlight domain as a site administrator.

2. Register the application at https://<spotlight_domain>/oauth2/applications/register/

3. 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

4. A Client ID and Client Secret are automatically generated for 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.

1. The authorization endpoint is https://<spotlight_domain>/oauth2/authorize/

2. Submit a GET request to the authorization endpoint - https://<spotlight_domain>/oauth2/authorize/?client_id=<client_id>&response_type=code&redirect_uri=<redirect_uri>

3. The user needs to follow the authorization flow in the browser.

4. Once Spotlight has successfully authenticated the user, a dialog will prompt the user to authorize the app. If the user clicks "Allow", the 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

1. The token endpoint is https://<spotlight_domain>/oauth2/token/.

2. 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>

3. An access_token is returned in the response which can be used to make further requests to the API.

Step 4 - Making requests

curl 'https://public-api.wazoku.com/api/v4/challenges?access_token=<access_token>'

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".

See also

• Wazoku Open API Backwards Compatibility Policy

• Wazoku glossary

• Report data points

 

---