About this guide

This guide will cover how to host the OpenBullet API and how to connect it to your OpenBullet client.

Getting started

First things first, you need to download the API from here. Then make sure you have the dotnet core sdk 2.2 installed. The dotnet core sdk is available for Windows, MacOS or Linux so you can host this web API on any VPS or any host that gives you root access.

Configuration

If you open the appsettings.json file you will see at the beginning 3 editable fields:

  • db - the LiteDB file where users will be stored (if the file does not exist it will be created automatically).
  • configFolder - the folder on the filesystem where the configs to be served are stored.
  • secretKey - the secret key used to access the /api/users endpoint and manage users.

Now create a Configs folder (it's already included in the precompiled version) and inside it, for the sake of this tutorial, make a folder called test and add any OpenBullet .loli config inside it.

Running

Open a terminal, navigate to the folder where OpenBulletAPI.dll is located and type dotnet ./OpenBulletAPI.dll. This will execute the application which by default will be remotely accessible on the HTTP port 5000 (or HTTPS port 5001 if configured).

Note: If for any reason it's not working when you type http://localhost:5000, I recommend using this command to start the webserver dotnet ./OpenBulletAPI.dll --urls "http://*:5000".

Administration

Download the OpenBullet Admin Panel from here. After you open it, set up your API URL (e.g. http://localhost:5000) and your secret key, then hit refresh. If no error is shown, you can proceed to add a user. For this tutorial, add a user by generating an api key and writing test inside the groups textbox.

Sources Setup

Now update OpenBullet to the latest version and go to the Settings > OB > Sources tab. Add a Source and type the path where configs are pulled from (by default it's api/configs e.g. http://localhost:5000/api/configs). After that, paste the Api Key of your user and save the settings.

Finally, go to the Configs Manager page and click on Rescan. If everything went right, any config on your remote test folder will be pulled down to the client. These configs exclusively reside in memory and editing/saving is disabled.

UserPass Authentication

If you want you can also use Username and Password to authenticate to the api. You will have to implement a new call to another external API (e.g. a website, forum) where the groups are returned to the OpenBullet API which will provide the correct configs to the user.

Own API

If you wish to implement your own API written in another language (nodejs, python, go, php...) you will need to follow some specifications to make it work with the original OpenBullet client.

The request sent by OpenBullet is a simple GET request with the Authorization header set. This can be:

  • Authorization: API_KEY if the user authenticates via Api Key
  • Authorization: Basic BASE_64 where BASE_64 is USER:PASS encoded as base64

The response of the API must be a Zip file containing in its root all the .loli configs you want the user to access.

On the latest versions of OpenBullet, if you place folders in the Zip file that you send back to the client, they will be interpreted as category names and displayed in the Config Manager accordingly.

The response can also have a Result header. In case that header's value is Error, OB will prompt to the user the contents of the body of the response (ASCII encoded).