API

This page is interesting to developers of Project-W, but also to people who want to write custom clients for it (like bash or python scripts or anything else). If the latter is the case then focus on the client-facing routes and ignore the runner-facing ones.

Note

If you want to develop a client that is intended to replace the current frontend (not just as an addition) then make sure that is has both an /activate and a /resetPassword route! The backend expects that the client has these since it puts them into the emails it sends to the users. Both routes should accept a token as a query string that contains the activation/password reset token. If you don’t do this, then the links in the emails the backend sends to the users will not work for your client.

General

The REST API of the backend is divided into three sections:

1. /api/users/*

2. /api/jobs/*

3. /api/runners/*

The first two are for the client and include routes to manage users and their jobs respectively. From now on we will call them client-facing routes. The third one is for the communication between the backend and its runners and should be ignored by the clients (runner-facing routes).

We made the following design decision regarding when to use GET, POST or PUT routes:

• GET: Requests are both safe and idempotent

• PUT: Requests are not safe but idempotent

• POST: Requests are neither safe nor idempotent

A safe operation is one that doesn’t cause a write to the database (only read). An idempotent request is one that returns the same data regardless of how often you request it (e.g. the returned data of the 10th request will be the same as the one of the 1st).

Additionally to the http status codes all client-facing routes will return a json object with a msg attribute which is string containing the response of the server in (more or less) human readable form. All responses in msg sent by client-facing routes are written in a way such that they can directly be displayed on the frontend of the client. However with some invalid requests the response may be generated by Flask, in these cases the msg attribute will still be present but maybe not as understandable by the user.

All negative responses (i.e. responses that do not have http status code 200) generated by client-facing routes (and not Flask itself) also return an errorType attribute in their json response that will contain a string with the type of error the server encountered with this request. Refer to Error types for all strings we use for this.

Quick reference

Resource	Operation	Description
	GET /api/about	Returns description and version of the backend
Jobs	POST /api/jobs/submit	Submit a new job
	GET /api/jobs/list	List all job-IDs associated with an user account
	GET /api/jobs/info	Get detailed information to all provided jobIds
	POST /api/jobs/abort	abort all jobs associated with provided jobIds
	POST /api/jobs/delete	delete all jobs associated with provided jobIds
	GET /api/jobs/downloadTranscript	Download transcript of a finished job.
Runners	GET /api/runners/create	Create a new runner and get its token.
	POST /api/runners/register	Runner tells Backend that it is now online.
	POST /api/runners/unregister	Runner tells Backend that it is now going offline.
	GET /api/runners/retrieveJobAudio	Runner retrieves audio data of the job that got assigned to it.
	POST /api/runners/retrieveJobInfo	Runner retrieves information about the job that got assigned to it.
	POST /api/runners/submitJobResult	Runner submits the result (transcript or error msg) of a finished job.
	POST /api/runners/heartbeat	Runner tells backend that it is still online and asks for a job or tells about the progress of the current job.
Users	POST /api/users/signup	Create a new user account.
	POST /api/users/activate	Activate an user account by confirming email address.
	POST /api/users/login	Log in into an user account.
	GET /api/users/requestPasswordReset	Request password reset email
	POST /api/users/resetPassword	Reset user password with Token from email.
	GET /api/users/info	Get account information of an user account
	POST /api/users/delete	Delete an user account
	POST /api/users/changePassword	Change password of an user account
	POST /api/users/changeEmail	Change email address of an user account
	GET /api/users/resendActivationEmail	Resend confirmation email
	POST /api/users/invalidateAllTokens	Revoke all user sessions

Routes in detail

GET /api/about

Returns a brief description of Project-W, a link to the GitHub repository and the version currently running on the system.

Response JSON Object:

• msg (string) – Description of Project-W

• sourceCode (string) – Link to the GitHub repository with the source code of the backend

• version (string) – Version of the backend as set by setuptools-scm

Status Codes:

• 200 OK – Responding with info

POST /api/jobs/abort

Abort all jobs with the corresponding job ids from the jobIds array. The backend will mark these jobs as to be aborted and notify the runner about that on the next heartbeat which will then cancel it and submit it as failed. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• jobIds has to have the correct format as described below. ErrorType: invalidRequest

• The status of all jobs in jobs shouldn’t be one of the following: SUCCESS, FAILED, DOWNLOADED. If one of the jobs in the array doesn’t meet this then none of the jobs will be aborted. ErrorType: invalidRequest

• If trying to abort the job of another user (e.g. if one of jobIds doesn’t belong to this user): Currently logged in account has to be admin. ErrorType: permission.

• If trying to abort the job of another user (e.g. if one of jobIds doesn’t belong to this user): A job with the provided jobId has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• jobIds – List of Job-IDs as a string, separated by commas, e.g. 2,4,5,6.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of invalidRequest, permission, notInDatabase for this route. Refer to Error types

Status Codes:

• 200 OK – All jobs aborted successfully.

• 400 Bad Request – With errorType invalidRequest.

• 403 Forbidden – With errorType permission.

• 404 Not Found – With errorType notInDatabase.

POST /api/jobs/delete

Delete all jobs with the corresponding job ids from the jobIds array. These jobs will be permanently removed from the backends database. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• jobIds has to have the correct format as described below. ErrorType: invalidRequest

• The status of all jobs in jobs has to be one of the following: SUCCESS, FAILED, DOWNLOADED. If one of the jobs in the array doesn’t meet this then none of the jobs will be aborted. Use /api/jobs/abort before calling this to remove these jobs. ErrorType: invalidRequest

• If trying to abort the job of another user (e.g. if one of jobIds doesn’t belong to this user): Currently logged in account has to be admin. ErrorType: permission.

• If trying to abort the job of another user (e.g. if one of jobIds doesn’t belong to this user): A job with the provided jobId has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• jobIds – List of Job-IDs as a string, separated by commas, e.g. 2,4,5,6.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of invalidRequest, permission, notInDatabase for this route. Refer to Error types

Status Codes:

• 200 OK – All jobs were successfully deleted.

• 400 Bad Request – With errorType invalidRequest.

• 403 Forbidden – With errorType permission.

• 404 Not Found – With errorType notInDatabase.

GET /api/jobs/downloadTranscript

Download the transcript of a successfully completed job in the form of a long String. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• A job with the provided jobId has to exist. ErrorType: notInDatabase.

• If trying to access job of another user (e.g. if one of jobIds doesn’t belong to this user): Currently logged in account has to be admin. ErrorType: permission.

• The job with the provided jobId has to have a transcript as an attribute (meaning it needs to have finished without an error). ErrorType: operation

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Query Parameters:

• jobId – Job-ID of the job of which to download the transcript from.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of notInDatabase, permission, operation for this route. Refer to Error types

• transcript (string) – Finished transcript. You may want to store this as a file.

Status Codes:

• 200 OK – Returning the requested transcript.

• 400 Bad Request – With errorType operation.

• 403 Forbidden – With errorType permission.

• 404 Not Found – With errorType notInDatabase.

GET /api/jobs/info

Get all information related to the given jobs. This contains stuff like the filename, the used model or the current status and progress. By giving a list of jobIds you can access the information of multiple jobs with just one request. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• jobIds has to have the correct format as described below. ErrorType: invalidRequest

• If trying to access job of another user (e.g. if one of jobIds doesn’t belong to this user): Currently logged in account has to be admin. ErrorType: permission.

• If trying to access job of another user (e.g. if one of jobIds doesn’t belong to this user): A job with the provided jobId has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Query Parameters:

• jobIds – List of Job-IDs as a string, separated by commas, e.g. 2,4,5,6.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of invalidRequest, permission, notInDatabase for this route. Refer to Error types

• jobs (list_of_objects) – Info of all requested jobs. Each object can (but doesn’t have to) contain the following fields: jobId: integer, fileName: string, model: string, language: string, error_msg: string, only exists if this job is in failed state (and even then not always), status: object that can contain the fields ‘step: string’, ‘runner: integer’, ‘progress: float’.

Status Codes:

• 200 OK – Returning the requested job infos.

• 400 Bad Request – With errorType invalidRequest.

• 403 Forbidden – With errorType permission.

• 404 Not Found – With errorType notInDatabase.

GET /api/jobs/list

Get a list of all jobs either of this user account or of another user account/all users (only possible if you are admin). Returns all jobs as a list of job ids. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• If trying to list jobs of other users accounts (e.g. if email or all is not empty): Currently logged in account has to be admin. ErrorType: permission.

• If trying to list all jobs of another user (e.g. if email is not empty): An account with the provided email address has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Query Parameters:

• (optional) (email) – Set to 1 if you want to get all jobs of all accounts.

• (optional) – Email address of account of which you want to get all jobs from (leave empty to access all jobs of your own account).

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of permission, notInDatabase for this route. Refer to Error types

• jobIds (list_of_integers) – JobIds of all requested jobs.

Status Codes:

• 200 OK – A new job with the submitted details was created successfully.

• 400 Bad Request – With errorType notInDatabase.

• 403 Forbidden – With errorType permission.

POST /api/jobs/submit

Submit a new transcription job by posting the file as well as some job details. The backend will create a new job, immediately assign it to a free runner (if one exists) and return its jobID. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• The user to which the JWT Token belongs has to be activated (i.e. has to have confirmed their email address). ErrorType: permission.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• file – Audio data that should be transcribed as a binary file

• model (optional) – Whisper model that should be used. One of: [ tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large ]. Defaults to: small.

• language (optional) – Language to transcribe to (spoken language in audio file). One of: [ af, am, ar, as, az, ba, be, bg, bn, bo, br, bs, ca, cs, cy, da, de, el, en, es, et, eu, fa, fi, fo, fr, gl, gu, ha, haw, he, hi, hr, ht, hu, hy, id, is, it, ja, jw, ka, kk, km, kn, ko, la, lb, ln, lo, lt, lv, mg, mi, mk, ml, mn, mr, ms, mt, my, ne, nl, nn, no, oc, pa, pl, ps, pt, ro, ru, sa, sd, si, sk, sl, sn, so, sq, sr, su, sv, sw, ta, te, tg, th, tk, tl, tr, tt, uk, ur, uz, vi, yi, yo, yue, zh ] or the same languages but written out (first letter in uppercase), e.g. English or German. If left away then whisper will detect the language automatically.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – permission for this route. Refer to Error types

• jobId (integer) – ID of the newly created job.

Status Codes:

• 200 OK – A new job with the submitted details was created successfully.

• 403 Forbidden – With errorType permission.

GET /api/runners/create

Create a new runner and get its runner Token. You need to call this route before you can configure and start you Runner. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token (of a user) has to be supplied in Authorization header.

• The user associated with that JWT Token has to be an admin.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Response JSON Object:

• msg (string) – Human-readable error message that tells you why the request failed (for debugging reasons).

• runnerToken (string) – Token of the newly created runner.

Status Codes:

• 200 OK – Runner successfully created and returning its token.

• 403 Forbidden – User is not an admin.

POST /api/runners/heartbeat

The runner tells the Backend that it is still online and asks if there is any job assigned to it at the same time. If the Runner is currently working on a job then it tells the Backend the current progress. This route should be called by the runner every 15 seconds. If it isn’t called for 60 seconds then the runner may be automatically unregistered by the Backend. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner has to currently be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Form Parameters:

• float progress (optional) – The progress of the current job as a float between 0 and 1. Will be processed up to a precision of 4 decimal digits (-> so 2 decimal digits if multiplied by 100 for percent representation)

Response JSON Object:

• error (string) – Human-readable error message that tells you why the request failed.

• jobAssigned (boolean) – If set to true, then the Backend has assigned a job to this Runner. false or null otherwise. Note that this will also return true if the Runner is already processing the job that got assigned to it.

Status Codes:

• 200 OK – Heartbeat acknowledged. Progress successfully updated.

• 400 Bad Request – Failed. Refer to error field for the reason.

POST /api/runners/register

The runner tells the backend that it is now online and capable of receiving jobs. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner can’t already be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat, so if this condition isn’t true then just wait a bit.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Response JSON Object:

• msg (string) – Human-readable success message.

• runnerID (integer) – ID under which the runner is registered at the backend

• error (string) – Human-readable error message that tells you why the request failed.

Status Codes:

• 200 OK – Runner successfully registered.

• 400 Bad Request – Failed. Refer to error field for the reason.

GET /api/runners/retrieveJobAudio

The runner retrieves the binary audio data of its job after it learned from the heartbeat response that the Backend assigned a job to it. Use /api/runners/retrieveJobInfo to get all the other data of the job. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner has to currently be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat.

• There has to be a job assigned to the runner associated with the given Runner Token.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Response JSON Object:

• error (string) – Human-readable error message that tells you why the request failed.

Status Codes:

• 200 OK – Just returning the binary audio data. In this case the Content-Type is audio/basic instead of application/json.

• 400 Bad Request – Failed. Refer to error field for the reason.

POST /api/runners/retrieveJobInfo

The runner retrieves the infos about its job after it learned from the heartbeat response that the Backend assigned a job to it. Use /api/runners/retrieveJobAudio to get the audio data. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner has to currently be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat.

• There has to be a job assigned to the runner associated with the given Runner Token.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Response JSON Object:

• error (string) – Human-readable error message that tells you why the request failed.

• jobID (integer) – ID of the assigned job

• model (string) – Whisper model that should be used for the job. May be null.

• language (string) – Language of the audio. May be null.

Status Codes:

• 200 OK – Returning information of the assigned job.

• 400 Bad Request – Failed. Refer to error field for the reason.

POST /api/runners/submitJobResult

The runner submits the result of the finished job by either submitting the transcript or an error message. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner has to currently be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Form Parameters:

• transcript – Text of the finished transcript. The job will get the status SUCCESS. Request has to either include this or error_msg.

• error_msg – Error that occurred during transcribing. The job will get the status FAILED. Request has to either include this or transcript.

Response JSON Object:

• error (string) – Human-readable error message that tells you why the request failed.

• msg (string) – Human-readable success message.

Status Codes:

• 200 OK – Received job result and successfully updated the jobs status.

• 400 Bad Request – Failed. Refer to error field for the reason.

POST /api/runners/unregister

The runner tells the backend that it is going offline and can’t accept any more jobs. The following conditions have to be met for this to succeed:

• Correct and valid Runner Token (that is known to the Backend) has to be supplied in Authorization header.

• The runner has to currently be registered. All runners will be unregistered automatically after 60-70 seconds since the last heartbeat.

Request Headers:

• Authorization – Has to be string “Bearer {Token}”, where {Token} is the Runner Token that the /runners/create route returned.

Response JSON Object:

• msg (string) – Human-readable success message.

• error (string) – Human-readable error message that tells you why the request failed.

Status Codes:

• 200 OK – Runner successfully registered.

• 400 Bad Request – Failed. Refer to error field for the reason.

POST /api/users/activate

Activate an user account by clicking on the link in the confirmation mail. The user will get the link with the token for this per email. The following conditions have to be met for this to succeed:

• The provided Token has to be valid and decoding it has to succeed. ErrorType: auth.

• An account with the email address that was encoded into the token has to exist. ErrorType: notInDatabase.

• The account can’t already be activated. ErrorType: operation.

Form Parameters:

• token – Activation token (delivered by email)

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of auth, notInDatabase, operation for this route. Refer to Error types

Status Codes:

• 200 OK – User successfully activated.

• 400 Bad Request – User not activated. Refer to errorType and msg for what went wrong.

POST /api/users/changeEmail

Change the email address of the currently logged in account. If you are currently logged in with an admin account you can also change the email address of another user account with provided email. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• The provided password has to match the accounts password. ErrorType: auth.

• If trying to delete other users account (e.g. if emailModify is not empty): Currently logged in account has to be admin. ErrorType: permission.

• If trying to delete other users account (e.g. if emailModify is not empty): An account with the provided email address has to exist. ErrorType: notInDatabase.

• Provided new email has to have the format of an email address (something`@`(sub)domain.`tld`) and its (sub)domain needs to be on the allow-list of the server. Refer to Description of backend config options. ErrorType: email.

• The new email can’t be already in use by another account. ErrorType: email.

• Sending a confirmation mail to the new email address has to succeed. ErrorType: email.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• password – Password of user account associated with the currently logged in account/emailModify

• newEmail – New email address that should be set for the user

• emailModify (optional) – Email of account that you want to access (leave empty if you want to access own account)

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of auth, permission, notInDatabase, email for this route. Refer to Error types

• allowedEmailDomains (string[]) – Exists only if msg==”’{email}’ is not a valid email address”. List of allowed email domains on this server. Can be empty which means that all domains are allowed. You probably want to show this to your users.

Status Codes:

• 200 OK – Email changed successfully. Confirmation mail was sent successfully.

• 400 Bad Request – With errorType notInDatabase and email.

• 403 Forbidden – With errorTypes permission and auth.

POST /api/users/changePassword

Change the password of the currently logged in account. If you are currently logged in with an admin account you can also change the password of another user account with provided email. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• The provided password has to match the accounts password. ErrorType: auth.

• If trying to delete other users account (e.g. if emailModify is not empty): Currently logged in account has to be admin. ErrorType: permission.

• If trying to delete other users account (e.g. if emailModify is not empty): An account with the provided email address has to exist. ErrorType: notInDatabase.

• Provided new password has be at least 12 characters long and has to include at least one lower case letter, upper case letter, digit and special character. ErrorType: password.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• password – Password of user account associated with the currently logged in account/emailModify

• newPassword – new password that should be set for this account

• emailModify (optional) – Email of account that you want to access (leave empty if you want to access own account)

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of auth, permission, notInDatabase, password for this route. Refer to Error types

Status Codes:

• 200 OK – Password change successful.

• 400 Bad Request – With errorType notInDatabase and password.

• 403 Forbidden – With errorTypes permission and auth.

POST /api/users/delete

Delete the currently logged in account with all information associated with it. If you are currently logged in with an admin account you can also delete another user account with provided email. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• The provided password has to match the accounts password. ErrorType: auth.

• If trying to delete other users account (e.g. if emailModify is not empty): Currently logged in account has to be admin. ErrorType: permission.

• If trying to delete other users account (e.g. if emailModify is not empty): An account with the provided email address has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Form Parameters:

• password – Password of user account associated with the currently logged in account/emailModify

• emailModify (optional) – Email of account that you want to access (leave empty if you want to access own account)

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of auth, permission, notInDatabase for this route. Refer to Error types

Status Codes:

• 200 OK – User account gets deleted.

• 400 Bad Request – With errorType notInDatabase.

• 403 Forbidden – With errorTypes permission and auth.

GET /api/users/info

Get the account information of the currently logged in account. If you are currently logged in with an admin account you can also get account information of another user account with provided email. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• If trying to access other users info (e.g. if email is not empty): Currently logged in account has to be admin. ErrorType: permission.

• If trying to access other users info (e.g. if email is not empty): An account with the provided email address has to exist. ErrorType: notInDatabase.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Query Parameters:

• (optional) (email) – Email of account that you want to access (leave empty if you want to access own account)

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of permission, notInDatabase for this route. Refer to Error types

• email (string) – Email address of the account

• isAdmin (bool) – Whether the account is an admin account

• activated (bool) – Whether the account is activated

Status Codes:

• 200 OK – Returns account information.

• 400 Bad Request – With errorType notInDatabase.

• 403 Forbidden – With errorType permission.

POST /api/users/invalidateAllTokens

Invalidate all JWT Tokens for the currently logged in account. This means that all browser/client sessions will be revoked and the user has to log in using their email and password again. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

Status Codes:

• 200 OK – All Tokens were invalidated successfully.

POST /api/users/login

Log in into an user account. This will return a JWT Token that needs to be used for authentication in routes that require it. The following conditions have to be met for this to succeed:

• An account with the provided email address has to exist. ErrorType: auth.

• The provided password has to match the accounts password. ErrorType: auth.

Form Parameters:

• email – Email address of user

• password – Password of user account associated with email

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – auth for this route. Refer to Error types

• accessToken (string) – JWT Token

Status Codes:

• 200 OK – Successfully logged in.

• 400 Bad Request – Login not successful. Refer to errorType and msg for what went wrong.

GET /api/users/requestPasswordReset

Request a password reset email for a user account. The following conditions have to be met for this to succeed:

• An account with the provided email address has to exist (if this condition doesn’t hold, then no mail will be sent but the route still returns status 200). ErrorType: email.

• Sending the email has to succeed. ErrorType: email.

Query Parameters:

• email – Email address of user

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – email for this route. Refer to Error types

Status Codes:

• 200 OK – If account with email exists, then the mail was successfully sent. Else nothing.

• 400 Bad Request – Error when trying to sent email.

GET /api/users/resendActivationEmail

Resend the confirmation email for the currently logged in account. The following conditions have to be met for this to succeed:

• Correct and valid JWT Token has to be supplied in Authorization header. No errorType field.

• The account can’t already be activated. ErrorType: operation.

• Sending a confirmation mail to the email address has to succeed. ErrorType: email.

Request Headers:

• Authorization – Has to be string “Bearer {JWT}”, where {JWT} is the JWT Token that the login route returned.

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of operation, email for this route. Refer to Error types

Status Codes:

• 200 OK – Confirmation email was sent successfully.

• 400 Bad Request – Nothing happens.

POST /api/users/resetPassword

Reset a users password after getting the password reset email. The following conditions have to be met for this to succeed:

• Provided new password has be at least 12 characters long and has to include at least one lower case letter, upper case letter, digit and special character. ErrorType: password.

• The provided Token has to be valid and decoding it has to succeed. ErrorType: auth.

• An account with the email address that was encoded into the token has to exist. ErrorType: notInDatabase.

Form Parameters:

• token – Password reset token (delivered by email)

• newPassword – new password that should be set for this account

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of password, auth, notInDatabase for this route. Refer to Error types

Status Codes:

• 200 OK – Password successfully changed.

• 400 Bad Request – Password not changed. Refer to errorType and msg for what went wrong.

POST /api/users/signup

Create a new user account by setting its email and password. The following conditions have to be met for this to succeed:

• Signup of new accounts can’t be disabled on this server. Refer to Description of backend config options. ErrorType: serverConfig.

• Provided email has to have the format of an email address (something`@`(sub)domain.`tld`) and its (sub)domain needs to be on the allow-list of the server. Refer to Description of backend config options. ErrorType: email.

• Provided password has be at least 12 characters long and has to include at least one lower case letter, upper case letter, digit and special character. ErrorType: password.

• The email can’t be already in use by another account. ErrorType: email.

• Sending a confirmation mail to the email address has to succeed. ErrorType: email.

Form Parameters:

• email – Email address of new user

• password – Password of new user

Response JSON Object:

• msg (string) – Human-readable response message designed to be directly shown to users

• errorType (string) – One of serverConfig, email, password for this route. Refer to Error types

• allowedEmailDomains (string[]) – Exists only if msg==”’{email}’ is not a valid email address”. List of allowed email domains on this server. Can be empty which means that all domains are allowed. You probably want to show this to your users.

Status Codes:

• 200 OK – User successfully created. Email confirmation mail successfully sent.

• 400 Bad Request – User not created, no confirmation mail was sent. Refer to errorType and msg for what went wrong.

Error types

Why do we need error types? Sometimes the client wants to have additional information about why a particular request failed that can easily be automatically processed. For example if you have a Signup form the client may want to highlight the field in the frontend that caused the error. So if the errorType is email then highlight the email field. If it is password then highlight the password field. For consistency reasons and to make client programming easier (so you don’t have to check all the time if the errorType attribute exists and is not null this time) we included this field on all negative responses (i.e. responses that do not have http status code 200) that get generated by all client-facing routes (and not Flask itself).

The following strings can be returned in the errorType attribute. Please note that we may add additional types with future updates if necessary.

• serverConfig

  • error due to configuration of server

  • e.g.: disableSignup is set in config

• email

  • error due to email being invalid in some way

  • e.g. when trying to signup or changing email to something that is not an email address

  • not for login or any kind of authentication, only when it is NOT an authentication parameter (see auth for that)!

• password

  • error due to password being invalid in some way

  • e.g. when trying to signup or changing password to something invalid like a password which is too short

  • not for login or any kind of authentication, only when it is NOT an authentication parameter (see auth for that)!

• invalidRequest

  • a generic error type for if the request that you made was somehow invalid (probably regarding the query string/form attributes you used)

  • If email and password wouldn’t have their own more specific error type, then they would also fall into this category

  • e.g. if the provided list of jobIds in /jobs/info isn’t formatted correctly

• permission

  • user doesn’t have permission to access this route/resource/feature

  • e.g. admin exclusive routes, user tries to modify other users or the user is not activated even though that is required for this route

  • often combined with http status code 403

  • not for authentication failures, see auth for that!

• auth

  • authentication failed for some reason

  • e.g. invalid credentials, invalid password, invalid token, etc.

• notInDatabase

  • requested ressource is not in database

  • e.g. when no user with the provided email address could be found in the database

• operation

  • invalid operation at this time (e.g. some condition for this operation that is not part of the request itself is not met)

  • e.g. activate_user when user is already activated