An overview of our API, how to use it
Accessing the Public API
The Public API, as well as a list of all available endpoints, can be accessed here: public-api.wazoku.com
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/v1/challenges' -H 'Authorization: Token <token>:<user_id>'
For example, if my token is “thisismytoken”, the request would look something like this:
curl 'https://public-api.wazoku.com/api/v1/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.
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>'
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.
Generating Public API Tokens
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.
Step 1 - App Registration
- Login to the Spotlight domain as Admin.
- 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
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).
Filtering and ordering
In most cases, listing endpoints allow you to order the results and filter them. For ordering, use order parameter. It usually 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. Its format: [min_value]..[max_value], either minimal or maximal value can be omitted.