Users

Security code

A six-digit security code is generated at the app's startup sequence. It can be found in logs.

This code is used in special cases where you're not logged in as operator but need operator privileges, like creating a new operator user for example.

User names

if a user name contains a @ character, it's considered an online account. If not, it is a local account.

The rightmost part of a username with a @ is the server it is attached to.

User types

  • 0 : Operators (also called admins)
  • 1 : Regular user
  • 2 : Guest

Guests have limited access (they can't have favorites).

Online users

Users are considered online if they have a @ in their name.

For edit routes you'll need to provide your onlineAuthorization token along with the authorization one.

Language preferences

Users can have two languages settings. Each uses a ISO639-2B code :

  • main_series_lang : Main language to use
  • fallback_series_lang : Language to use if the main one isn't available on a particular series.

NOTE: the property name has "series" in it for legacy reasons, and is not specific to series.

If all else fails, the default title/name will be used (specific to each song/tag).

Get all users

getUsers Authentication needed Frontend needs to be restricted or open

List all users in database. If listed by a non-admin, even users with flag_public at false are listed.

Response
[
    {
        type: 0,
        avatar_file: 'abcdefghijkl.png',
        login: 'axel@kara.moe',
        nickname: 'AxelTerizaki',
        last_login_at: 2021-05-04 12:09:11
        flag_online: true  // True if the user has been using the frontend recently (15 minutes ago at least by default)
    },
    ...
]
Response
{
    code: 500,
    message: {
        code: 'USER_LIST_ERROR'
    }
}

Create user

createUser No authentication needed Frontend needs to be restricted or open

Create a new user.

Auth is optional. In order to create an operator (admin) account, you need either the security code or an auth token belonging to a operator user.

You don't need either to create regular user accounts.

Request
{
    login: 'axel@kara.moe',
    password: 'blablabla',
    role: 'admin' // user or admin
    securityCode: 123456 // optional
}
Response
{
    code: 200, 
    message: {
        code: 'USER_CREATED'        
    }
}

Not enough privileges to create an admin account or wrong security code.

Response
{
    code: 403,
    message: {
        code: 'UNAUTHORIZED'
    }
}

You cannot create online accounts with the name admin

Response
{
    code: 403,
    message: {
        code: 'USER_CREATE_ERROR',
        data: 'Admin accounts are not allowed to be created online'
    }
}

Admin has disabled online account creation

Response
{
    code: 403,
    message: {
        code: 'USER_CREATE_ERROR',
        data: 'Creating online accounts is not allowed on this instance'
    }
}
Response
{
    code: 411,
    message: {
        code: 'PASSWORD_TOO_SHORT'        
    }
}

Get single user

getUser Authentication needed Frontend needs to be restricted or open

Get full user profile. If listed by a non-admin, even users with flag_public at false are listed.

Request
{
    username: 'axel@kara.moe'
}
Response
{
    code: 500,
    message: {
        code: 'USER_VIEW_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'USER_VIEW_ERROR'
    }
}

Delete user (locally)

deleteUser Operator user required Frontend can be closed, restricted or open

Delete a user. This is an admin-only route used in the system panel.

Regular users can delete their own accounts with another route.

Request
{
    username: 'axel@kara.moe'
}
Request
{
    code: 200,
    message: {
        code: 'USER_DELETED'
    }
}
Response
{
    code: 406,
    message: {
        code: 'USER_DELETE_ADMIN_DAMEDESU'
    }
}
Response
{
    code: 500,
    message: {
        code: 'USER_DELETE_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'USER_NOT_EXISTS'
    }
}

Edit user (locally)

editUser Operator user required Frontend can be closed, restricted or open

Edit a user (from the system panel).

If it's an online user, only editing its type and flag_tutorial_done is permitted.

If it's a local user, all fields are allowed.

The avatar

Before sending this request and if you want to change a user's avatar, you need to send it first through the REST API /api/importfile. See uploading files for more info.

Make Axel an admin and change his avatar :

Request
{
    login: 'axel',
    type: 0
    avatar: 'abdecfgh.png'
}
Response
{
  code: 200
  message: {
    code: 'USER_EDITED'    
  }
}
Response
{
    code: 500,
    message: {
        code: 'USER_EDIT_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'USER_NOT_EXISTS'
    }
}
Response
{
    code: 400,
    message: {
        code: 'USER_EDIT_ERROR'
    }
}
Response
{
    code: 409,
    message: {
        code: 'USER_EDIT_ERROR'
    }
}
Response
{
    code: 400,
    message: {
        code: 'PASSWORD_TOO_SHORT'
    }
}

Reset user password

resetUserPassword No authentication needed Frontend can be closed, restricted or open

Reset a user's password.

Resetting a local user password's needs the security code.

Resetting a online user password will fail if user hasn't entered an email in their profile. Otherwise, a mail will be sent to the user with a link to reset their password.

Request
{
  username: 'axel',
  password: 'lol',
  securityCode: 123456
}
Response
{
    code: 200,
    message: {
        code: 'USER_RESETPASSWORD_SUCCESS'
    }
}
Response
{
    code: 200,
    message: {
        code: 'USER_RESETPASSWORD_ERROR'
    }
}

Get User (my account)

getMyAccount Authentication needed Frontend can be closed, restricted or open

Get your own account information.

Your authentification token is used to identify you and return your information.

See Get User response. All fields which return null will now return something, save for password.
Response
{
    code: 500,
    message: {
        code: 'USER_VIEW_ERROR'
    }
}

Delete user (my account)

deleteMyUser Normal user required Frontend can be closed, restricted or open

Delete your own account (locally).

This does not affect your online account.

Response
{
    code: 200,
    message: {
        code: 'USER_DELETED'
    }
}
Response
{
    code: 500,
    message: {
        code: 'USER_DELETE_ERROR'
    }
}

Edit user (my account)

editMyAccount Operator user required Frontend can be closed, restricted or open

Edit your own profile.

This affects your online account if your user is an online one.

You'll need to provide an onlineAuthorization token to edit your online account.

See the Edit User request for more information.

If you're a online user, your online token will be displayed.

Response
{
    code: 200
    message: {
        code: 'USER_EDITED'
        data: {
            onlineAuthorization: <online token>
        }
    }
}
Response
{
    code: 404
    message: {
        code: 'USER_NOT_EXISTS'
    }
}
Response
{
    code: 403
    message: {
        code: 'GUESTS_CANNOT_EDIT'
    }
}
Response
{
    code: 400
    message: {
        code: 'USER_EDIT_ERROR'
    }
}
Response
{
    code: 403
    message: {
        code: 'USER_CANNOT_CHANGE_TYPE'
    }
}
Response
{
    code: 409
    message: {
        code: 'USER_EDIT_ERROR'
    }
}
Response
{
    code: 400
    message: {
        code: 'PASSWORD_TOO_SHORT'
    }
}

Convert my local user to online

convertMyLocalUserToOnline Normal user required Frontend can be closed, restricted or open

Convert my own local account to an online one

Your authentification token is used to identify you and return your information.

You still need to provide some information :

Request
{
  instance: 'kara.moe' // create user on kara.moe
  password: 'lol',     // your local password to confirm creation  
}

You get your onlineAuthorization token with the response :

Response
{
    code: 200,
    message: {
        code: 'USER_CONVERTED',
        data: {
            token: 'abcdefgh',
            onlineToken: 'abcdefghijkl'
        }
    }
}
Response
{
    code: 500,
    message: {
        code: 'USER_CONVERT_ERROR'
    }
}

User admin cannot be converted.

Response
{
    code: 500,
    message: {
        code: 'ADMIN_CONVERT_ERROR'
    }
}
Response
{
    code: 400    
}

Convert my online user to local

convertMyOnlineUserToLocal Normal user required Frontend can be closed, restricted or open

This is basically to delete your online account. This will thus remove your data from the server you're logged on, but keep your account local.

Use with care.

Your authentification token is used to identify you and return your information.

You still need to provide your password for confirmation

Request
{
  password: 'lol'
}

You get your new authorization token with the response :

Response
{
    code: 200,
    message: {
        code: 'USER_DELETED_ONLINE',
        data: {
            token: 'abcdefgh',            
        }
    }
}
Response
{
    code: 500,
    message: {
        code: 'USER_DELETE_ERROR_ONLINE'
    }
}
Response
{
    code: 400,    
}

Refresh user's anime list

refreshAnimeList Normal user required Frontend can be closed, restricted or open

Triggers an anime list refresh. This asks the user's attached server to refresh the list from the selected anime list provider. Once done it'll get pushed to the user's profile on the local app.

The request uses the authorization and onlineAuthorization headers to work.

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'REFRESH_ANIME_LIST_ERROR'
    }
}

Get user's anime list's songs

getAnimeList Normal user required Frontend can be closed, restricted or open

Returns songs based on the user's anime list.

See getKaras for more information on this command's parameters.

See getKaras for succesful responses.
Response
{
    code: 500,
    message: {
        code: 'ANIME_LIST_VIEW_ERROR'
    }
}

Get user's anime list's songs

getAnimeList Normal user required Frontend can be closed, restricted or open

Returns songs based on the user's anime list.

See getKaras for more information on this command's parameters.

See getKaras for succesful responses.
Response
{
    code: 500,
    message: {
        code: 'ANIME_LIST_VIEW_ERROR'
    }
}
Backgrounds Quiz Games