Table of Contents
On this page

Using the documentation

Since Redoc is readonly, in the following section we will focus only on using Swagger UI.

Protected endpoints

Now that you have a UI for the documentation, you can see all the endpoints. You will see that some of them have a lock symbol right before the collapse/expand arrow. When you see this symbol next to an endpoint, it means that the endpoint is protected and can only be accessed when authenticated with an account with proper permissions.

Authentication

In Swagger UI, you will see an Authorize button. Clicking it will open a modal where you will find two sections:

  • AuthToken - where you will have to enter a valid auth token
  • ErrorReportingToken - where you will have to enter a valid error reporting token

Below, we will walk you through on how to find both tokens. For now, let's close the modal.

Generating AuthToken

This token is required with most of the Dotkernel API endpoints. There are two entities that generate this type of token: (super)admins and users. Depending on the endpoint description, you will know which one you need to use. Examples:

  • /user: the description says Admin lists user accounts - it means that you need an AccessToken with (super)admin privileges
  • /user/my-account: the description says User fetches their own account - it means that you need an AccessToken with user privileges

In the UI, find a section called AccessToken, toggle the /security/generate-token (Generate access token) endpoint and click the Try it out button. Under the Access token generation request you will find a textarea prepopulated with a JSON object. You will have to change the value of username and password. See this guide for the credentials.

After you have filled out the credentials, click on the Execute button below the textarea. This will send the request to your instance of Dotkernel API. If everything went well, under the textarea you should see:

  • the curl request that was made
  • the Request URL the request was sent to
  • the Server response with 200 OK response code and the Response body with a JSON object containing token_type, expires_in, access_token and refresh_token.

Save the refresh_token somewhere, you will need it later

Now copy the value of access_token (make sure you copy all the characters, without the surrounding double quotes) and go back up to the Authorize button and click it to open the auth modal. Paste the copied token as the value of the AuthToken and click on the Authorize button you see under the input field. The Authorize button has now changed to Logout. You can close the modal.

From here, Swagger UI will remember the AuthToken until you close/refresh the browser tab. Also, it will automatically append the Authorization header to each request, allowing you to make authorized API calls.

If you need to switch to an account with different privileges, you go again to the Authorize button, click on it to open the auth modal, and click Logout for the AuthToken. Then paste the new token as the value of the AuthToken, click on the Authorize button, close the modal and continue using the UI authenticated with the new account.

Refreshing AuthToken

By default, auth tokens expire in 1 day. If you make an API call, and you receive an error telling you that your auth token is expired, you need to either generate a new token (as seen above) or refresh the existing one using the refresh_token received when generating the current token.

In order to refresh the auth token, you find the same section called AccessToken, toggle the /security/refresh-token (Refresh access token) endpoint and click the Try it out button. Under the Access token refresh request you will find a textarea prepopulated with a JSON object. You will have to change the value of refresh_token to the refresh token of your current auth token.

Once done, click on the Execute button below the textarea. This will send the request to your instance of Dotkernel API. If everything went well, under the textarea you should see the same details:

  • the curl request that was made
  • the Request URL the request was sent to
  • the Server response with 200 OK response code and the Response body with a JSON object containing token_type, expires_in, access_token and refresh_token.

From here, you will follow the same steps:

  • copy the access_token
  • go to the Authorize button to open the auth modal
  • paste the new token and click on Authorize
  • close the modal

Generating ErrorReportingToken

Just like the AuthTokens, ErrorReportingTokens are used to make authorized API calls. The difference is that this token applies only to one specific endpoint: /error-report (Report an error to the API). This endpoint is intended to be used by third-party applications and frontends to report an error back to the API.

This endpoint does not require AuthTokens

In order to generate this token, follow this guide.

Once you have the error reporting token, go again to the Authorize button, paste the new token as the value of the ErrorReportingToken, click on the Authorize button and close the modal. Now you're ready to report errors to your instance of Dotkernel API.

Making API calls

The UI does not use confirmation messages before making an API call so double check any operation before executing it.

Once authorized in the UI, you can click on any endpoint to expand it. There you will find an overview of the endpoint, including:

  • Request method (DELETE, GET, PATCH, POST, PUT)
  • request URL (example: /resource)
  • Short description
  • Long description
  • Parameters - if this area says No parameters, then there are no parameters to fill out; else, make sure you fill out all the required parameters
  • Request body - if present, provides a textarea prepopulated with a JSON object describing the request
  • Responses - a list of possible HTTP status codes and their respective response bodies

Clicking the Try it out button will activate any parameter input fields and the request body textarea (if any). Clicking Cancel will deactivate them.

Make sure you fill out all the necessary data, then click on the Execute found button above Responses. This will send the request and return and display the API response. Once finished, you will see the response as the first item under Responses, including the HTTP status code and the response body.

You can repeat the request by clicking again on the Execute button. This will first clear the previous output and display the new response in the same place. Additionally, between two executions, you can manually clear any previous output using the Clear button next to the Execute button.