API

helloquiz has an OAuth2 API which can be used for various operations such as adding/editing quizzes, editing account details, and more.

Gaining access

As of now, access to the API is only given upon request. If you wish to access the API, join the Discord, and send a message explaining your intended use case and estimated usage rates.

Endpoints

A full documentation of endpoints is available here, with an interactive API explorer.

Authentication

Getting tokens

The API supports OAuth2's authorization code grant flow. This is as follows:

• Redirect your users to /oauth2/authorize?[parameters]. The parameters include the following:
  • client_id: your application's registered client ID
  • redirect_uri: your application's registered redirect URI, which will reeceive the authorization code.
  • response_type: must be set to code
  • scope: a list of scopes, separated by spaces. See the Scopes section below.
  • state: optional, but encouraged - used to prevent CSRF attacks. The server will return this to you in your response
• Receive the authorization code. Once the user has accepted or rejected your login attempts, the authorization code will be returned to your redirect URI:
  • If they didn't authorize the app, it will be formatted as [redirect_uri]/?error=access_denied&error_description=The+user+denied+you+access&state=[state]
  • If they authorized the app, it will be formatted as [redirect_uri]/?code=[authorization_code]&scope=[scopes]&state=[state].
• Exchange the authorization code for a token by sending a POST request to /api/oauth2/token with the following paramters:
  • client_id: your application's registered client ID
  • client_secret: your application's registered client secret
  • code: the authorization code you just received
  • grant_type: must be set to authorization_code
  • redirect_uri: your application's registered redirect URI
• If this request succeeds, you will receive a JSON-formatted response, including an access_token (which expires in a day) and a refresh_token which you can use to recieve a new access token.

Once you have received your access token, in order to use it for requests, set the Authorization header to Bearer [token].

Refreshing tokens

In order to exchange your refresh token for an access token, send a POST request to /api/oauth2/token with the following parameters:

• client_id: your application's registered client ID
• client_secret: your application's registered client secret
• code: the refresh token
• grant_type: must be set to refresh_token
• redirect_uri: your application's registered redirect URI If this request succeeds, you will receive a JSON-formatted response, including an access_token (which expires in a day) and a refresh_token which you can use to recieve a new access token.

Revoking tokens

If you want to revoke a token, send a POST request to api/oauth2/token/revoke with the following parameters:

• client_id: your application's registered client ID
• client_secret: your application's registered client secret
• token: the token you wish to revoke
• token_type_hint: set it to refresh_token if this is a refresh token, or anything else if it is an access token

Scopes

Currently, the following scopes are available:

• account:anki:edit: Edit Anki mode settings
• account:connections:read: Read connected accounts
• account:connections:remove: Remove connected accounts
• account:name:edit: Edit username & handle
• account:statistics:read: Read game statistics, even if the user's privacy settings don't make them public
• admin:accounts:edit: Edit accounts (admin only)
• quiz:add: Add quizzes
• quiz:remove: Remove quizzes
• quiz:metadata:edit: Edit quiz metadata
• quiz:options:edit: Edit quiz settings
• quiz:questions:edit: Edit quiz questions"

→Open source