bjoernpetersen/musicbot-api

OpenAPI specification of the MusicBot REST-API

MusicBot-API

The OpenAPI specification for the MusicBot.

The latest documentation, automatically generated from the specification, can be found here: documentation.

Auth

This is a difficult subject as MusicBot instances are deployed in the local network. While a solution for automatic HTTPS has been found, end users still have to trust the server owner not to misuse their data, including their passwords. Of course official servers salt and hash user passwords to increase security, but a server owner may still make modifications to the code and gain access to clear-text passwords.

To minimize the trust required from end users to use the MusicBot, users may create a Guest account, which doesn't require a manually set password, is not persisted, and is limited to the default set of permissions. For user convenience and especially for user awareness of the option to omit the password, clients should not ask the user for a password in the login/registration process. A user may only be asked for their password at login if the server responded to the Guest login attempt with an AuthExpectation object requesting a password.

If a user wishes to set a password after logging in, for example to receive additional permissions or to be able to access the account from multiple devices, he may do so and by that will be upgraded to a Full user.

Note that clients should combine the login and registration process in order to make onboarding as simple as possible. The process should work as follows:

• Ask the user for his name (username).
• Try to register the user.
  • If successful -> done
• Try to log in as a Guest user (see Users section).
  • If successful -> done
  • Otherwise, if the AuthExpectation indicates a Guest user exists with different credentials, tell the user that their username is already taken. For Full users continue with the next step.
• Show a password field in addition to the username field and tell the user to enter their password.
• Try to login in as a Full user.
  • If successful -> done
• The user may retry logging in with different passwords or enter a different username.
  • If the username is changed, hide and clear the password field and return to step 2.

Tokens

Most endpoints require a bearer token for authentication/authorization. Issued tokens are JWT tokens with a JSON payload.

The payload has a at least a permissions array claim containing the permissions of the user. The possible permissions are defined in the MusicBot library: Permission.kt.

{
    "permissions": [
        "pause",
        "skip"
    ]
}

Users

Users are generally identified by their name (case-insensitive).

There are two types of users: Guest users and Full users.

Guest users:

• are only temporarily stored by the server (in memory)
• have an automatically generated password, for example an Android instance ID
• only have the default set of permissions

Full users:

• are permanently stored by the server (in a database)
• have an actual password chosen by the user
• can have additional permissions

When registering a new user, first a Guest user is created. That user can then be converted to a Full user by setting a password (see OpenAPI docs under changePassword).

Log in

All users log in using the same HTTP operation. The user name and password are supplied as HTTP Basic Authentication, please bear in mind that the USERNAME:PASSWORD string should be Base64-encoded using UTF-8. In case of Guest users, the "password" should be automatically generated by the client.