openapi: 3.0.1 info: title: PictureTasksAPI version: 1.0.1 termsOfService: https://picturetasks.net/tnc description: > See https://docs.picturetasks.net/100_api/ for a detailed API documentation (public part) servers: - url: https://ajax.picturetasks.net/ description: Local development environment paths: /image/section/add/: post: tags: - Image Management summary: Add Image Section description: > Adds a section to an existing image describing a specific point of interest, indicated by an svg loop overlaid on top of the image. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. imageId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The image identifier returned by `/image/upload` to create the section for. svg: type: string pattern: ^(?:(?:[M] -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} )(?:|[L] -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} |[C] -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} |[Q] -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} -?[\d]*\.[\d]{8},-?[\d]*\.[\d]{8} )*(z )?)$ description: > Some SVG path information to define the shape that marks the point of interest. Please note that an empty region is already created and therefore a single valid loop (or open shape) needs to be specified. color: type: string format: color pattern: ^[0-9a-fA-F]{8}$ minLength: 8 maxLength: 8 description: > A 4-byte hexadecimal value specifying a color in RGB-color space in the order RGBA (Big-Endian 32-bit unsigned integer with red as the lsb). Basically this means, that a value of #102030FF has a red value of 16, a green value of 32, a blue value of 48 and an alpha (opacity) of 255 (which is the maximum). required: - sid - imageId - svg - color responses: '200': description: > The section was created successfully. content: application/json: schema: type: object properties: sectionId: type: string format: uuid description: > The GUID representing this particular image. required: - sectionId '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /image/upload/: post: tags: - Image Management summary: Upload Image description: > Creates a new image with the provided image data. Also creates the generic section covering the entire image. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start` to create the image for. data: type: string format: byte description: > The image data. Please note that the image is going to be re-encoded to PNG regardless of the original file format. Even if the image was a PNG file in the first place, a re-encoding (and slight fuzzing) will happen to make sure the image is free of potential malicious content. Be aware that only PNG and JPEG files are supported. required: - sid - data responses: '200': description: > The image was created successfully. content: application/json: schema: type: object properties: imageId: type: string format: uuid description: > The GUID representing this particular image. sectionId: type: string format: uuid description: > The GUID representing the default section. required: - imageId - sectionId '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /device/register/: post: tags: - Session and User Management summary: Register a Device description: > Registers a new device. Should be used only on the first launch of a client on a new device. It may also be called if a user wishes to wipe their entire data. The credentials returned by this call should be kept persistent on the device to easily log in again and continue. requestBody: required: true description: > Contains some information to let the server know what kind of application the device is running. content: application/json: schema: type: object properties: interface: type: string maxLength: 255 description: > The identifier of the application used in the frontend. Basically just a plain text string that may contain some information about what type of executable is running on what type of operating system. required: - interface responses: '200': description: > The request was successful and the device has been registered. content: application/json: schema: type: object properties: device: type: string format: uuid description: > A UUID representing the device. password: type: string format: byte description: > A base64-representation of a generated password for the device. This password needs to be kept secret from now on and will never be requested again in the future without previous cryptographic processing. required: - device - password '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error400' '403': $ref: '#/components/responses/Error403' /device/login/: post: tags: - Session and User Management summary: Log in a device description: > Activates a device in a session, effectively loggin in the device. If the device has a user account attached to it, it will automatically be logged in as well. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. Can be reused in subsequent calls. token: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A base64-representation of the HMAC-SHA256 result of the salt + password + challenge with salt and challenge being returned by the initial call to `/session/start`. If `/session/challenge` was called in-between, its return value needs to be used instead as it replaces the original challenge generated by `/session/start`. The salt and challenge parameters are obsolete once the login has successfully been established. required: - sid - token responses: '200': description: > The login was successful and a device-authenticated session is now established. content: application/json: schema: type: object properties: user: description: > The user logged in to this specific device. If no user is present, this property is not present type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user identifier for the user. email: type: string description: > An email address to identify the user. Acts as the login name part of the login credentials. username: type: string description: > An optional visual representation of the user's name. This field might be omitted. tfa: type: boolean description: > Tells the client whether the user has 2-factor-authentication enabled. If so, some actions require an additional 2FA-code to be supplied. required: - uid - email - username - tfa '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /resource/text/: post: tags: - Resources summary: Request Text Resource description: > Requests a text resource with a given name. requestBody: required: true content: application/json: schema: type: object properties: resource: type: string pattern: ^[a-z0-9_\-]+$ description: > The name of the text resource. language: type: string pattern: ^[a-z]{2}$ description: > An ISO-language specifier identifying the language in which the text needs to be output. format: type: string pattern: ^(html|md|plain)$ description: > A text format to be displayed. Can either be `html` for html output, `md` for markdown output or `plain` for plain formatted text. required: - resource - language responses: '200': description: > The text was found. If the text is not available in the given language, the German version is returned. content: application/json: schema: type: object properties: title: type: string description: > A localized title for the text. text: type: string description: > The text in the desired format. language: type: string description: > The ISO-language specifier indicating the version of the text that is returned. Normally, this matches the requested language. In cases where the text is not available in the requested language, the German version is returned and `language` is returned as `de`. required: - title - text - language '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /task/image/set/: post: tags: - Tasks and Lists summary: Bind Image to Task description: > Binds an image section to a task. Both the image section as well as the task have to be created in advance by calling `/task/create`, `/image/upload` and `/image/section/add` respectively. Calling this function subsequently for the same task will replace the linked image section. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. taskId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The task identifier returned by `/task/create`. sectionId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The image section identifier returned by `/task/create` or `/section/add`. required: - sid - taskId - sectionId responses: '200': description: > The section has been successfully linked to the task. content: application/json: schema: type: object properties: taskId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The task id returned required: - taskId '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /task/update/: post: tags: - Tasks and Lists summary: Update Task Information description: > Updates task related information for all fields that actually are provided. Please note that for updating the task notes you need to call `/task/note`. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start` to create the task for. taskId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The task that is supposed to be updated. title: type: string description: > An updated title for the task. issue: type: string description: > A statement describing what is the issue. description: type: string description: > The detailed description of what to do. deadline: type: string format: date-time nullable: true description: > A deadline by which the task should be completed. priority: type: string pattern: ^(?:low|normal|high|critical)$ description: > A priority for the task. May help the assignee to decide where to start. required: - sid - taskId responses: '200': description: > The task has been updated successfully. content: application/json: schema: type: object properties: taskId: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The task id returned required: - taskId '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /task/create/: post: tags: - Tasks and Lists summary: Create New Task description: > Creates a new task requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start` to create the task for. title: type: string description: > A title indicating what the task is about. notes: type: string description: > Some personal notes on the task that will not be shared. description: type: string description: > A description for the task. required: - sid - title responses: '200': description: > The task has been saved successfully. content: application/json: schema: type: object properties: taskId: type: string format: uuid description: > The GUID representing this particular task. required: - taskId '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/verify/: post: tags: - Session and User Management summary: Verify New User description: > Verifies the email address of a newly registered user. Also, unifies the device account with the newly registered user account if a session is provided with a logged-in device. For verifying an updated email address, see `/email/verify`. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user identifier returned by `/user/register`. It is also contained in the user's verification email. code: type: string pattern: ^[0-9]{6}$ description: > The verification code sent via email to the user's email address. required: - uid - code responses: '200': description: > The email address has been verified. Any existing objects owned by the device are now owned by the user. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user's identifier returned. email: type: string format: email description: > The user's email address. username: type: string description: > The user's user name. required: - uid - email - username '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/register/resend/: post: tags: - Session and User Management summary: Resend Verification Email description: > In case a user needs their verification email re-sent to them, this action will do exactly this. Any code received earlier will stop working as a new validation code is going to be created. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The primary email address the user registered. Please note that, after 90 minutes, the registration attempt will have been erased and the call will fail with an unknown-user-error. Also, the user's account must not already have been verified. required: - sid - email responses: '200': description: > The verification email has been sent again with a new code. The code is valid for 90 minutes. After that, the registration needs to be started again. content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session id returned. required: - sid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/register/: post: tags: - Session and User Management summary: Register User description: > Adds a user to the system, effectively wrapping the device account. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The primary email address the user is going to register. An already registered email address can not be registered again. username: type: string pattern: ^.*[^ \r\n\t].*$ maxLength: 32 description: > A self-chosen user name (ideally the user's real name). password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A base64-encoded SHA256-hash of the user's password. language: type: string pattern: ^[a-z]{2}$ description: > An ISO-language identifier to be used as the main language for the user's account. required: - sid - email - username - password - language responses: '200': description: > The user was registered. The device account was not yet converted, instead, an email is sent to the user with a confirmation code that needs to be entered in the next step to actually convert the account. The code is valid for 90 minutes. After that, the registration needs to be started again. content: application/json: schema: type: object properties: uid: type: string format: uuid description: > The user's unique id (GUID). required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/password/change/: post: tags: - Session and User Management summary: Change User's Password description: > Changes a user's password. Requires the old password's hash to be provided, and a 2FA-token if 2FA is set up for the user. Also, all devices except the current one are logged out automatically and immediately. All their sessions are terminated and need to get re-established. A call to `/session/challenge` is required prior to executing this action. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > The password for the user in the same way as for `/user/login`. newPassword: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A hash of the user's new password. Please be aware that the salt is going to change as well so you might need to update your session cache accordingly. totp: type: string format: string pattern: ^[0-9]{6}$ description: > If the user has two-factor-authentication enabled, this action requires a valid TOTP key, regardless of the session's elevation status. If the user has no two-factor-authentication set, this parameter can be omitted. required: - sid - password - newPassword responses: '200': description: > The password was changed and a new salt has been applied as well. content: application/json: schema: type: object properties: salt: type: string format: byte description: > The new salt value, base64-encoded. required: - salt '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/password/lost/: post: tags: - Session and User Management summary: Lost Password description: > This method will request a password reset in case the password was lost. An email is sent to the user with a reset code that can be provided to `/user/password/lostreset`. The session needs a device to be logged in. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The primary email address registered for the user. totp: type: string pattern: ^[0-9]+$ description: > The 2FA-token valid at the current time. Required only if 2FA is set up for the user. required: - sid - email responses: '200': description: > The reset email was sent to the user's primary email address. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user's identifier returned. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/password/resetlost/: post: tags: - Session and User Management summary: Reset Lost Password description: > Resets a user's password requiring the reset code sent via email by a call to `/user/password/lost`. Please note that this also logs out all sessions on all devices (except the current one, if logged in). The session requires a device to be logged in. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The primary email address registered for the user. code: type: string pattern: ^[0-9]+$ description: > The code for the password reset sent to the user via email. newPassword: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A base64-encoded SHA256-hash of the user's new password. The UI should make sure to test for complexity and typos. required: - sid - email - code - newPassword responses: '200': description: > The password was changed and a new salt has been applied as well. content: application/json: schema: type: object properties: salt: type: string format: byte description: > The new salt value, base64-encoded. required: - salt '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/challenge/: post: tags: - Session and User Management summary: User Challenge description: > Basically the same as `/session/challenge`, but instead, the user is provided by their primary email address instead of derived from the session. This scenario is only needed for logging in a user. For all other use cases, calling `/session/challenge` is more advisable. The session requires a device to be logged in. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The user's primary email address that is used to log in. required: - sid - email responses: '200': description: > A challenge has been created and the user was identified content: application/json: schema: type: object properties: challenge: type: string format: byte description: > A base64-encoded representation of the challenge to be used in the password hash calculation process. salt: type: string format: byte description: > The salt value used in the password hash calculation, base64-encoded. required: - challenge - salt '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/login/: post: tags: - Session and User Management summary: Log in a user description: > Attaches a user to a device. If the device is already attached to a user, the login fails (even if it is the same user to be logged in). A call to `/user/challenge` is required first to generate a challenge and retrieve the salt for the user. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The primary email address registered for the user. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > The base64-encoded password hash calculated from `SHA256( challenge + SHA256( salt + password ) )`. required: - sid - email - password responses: '200': description: > The user has been logged in. The device account has been tied to the user as well. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user identifier for the user. username: type: string description: > The user's username as set up in the profile. verified: type: boolean description: > Tells the client whether the user has been verified or a verification needs to be performed first. Unless a user was verified, the device data will not be tied to the user's account. tfa: type: boolean description: > Tells the client whether the user has 2-factor-authentication enabled. If so, some actions require an additional 2FA-code to be supplied. required: - uid - username - verified - tfa '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/change/: post: tags: - Session and User Management summary: Change 2FA Secret description: > In case the secret needs to be changed but is still accessible, this action can be used to generate a new secret. Until it gets activated, the already existing secret stays valid. The session needs a user to be logged in. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. totp: type: string pattern: ^[0-9]+$ description: > The one time password shown by the authenticator app. required: - sid - totp responses: '200': description: > The 2FA has been changed and can be activated with `/user/tfa/activate` using a token derived from the new secret. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user's identifier returned. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/lost/: post: tags: - Session and User Management summary: Lost 2FA Token description: > This method will send an email to the user with a 6-digit code which needs to be used in a subsequent call to `/user/tfa/resetlost` to actually reset the 2-factor-authentication. The session needs a user to be logged into it. A call to `/session/challenge` is required in advance. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > The password for the user in the same way as for `/user/login`. required: - sid - password responses: '200': description: > An email has been sent to the user's primary email address containing a code that needs to be provided to a call to `/user/tfa/resetlost`. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user's identifier returned. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/activate/: post: tags: - Session and User Management summary: Activate 2FA description: > Verifies a 2FA-code for a set up secret to actually enable the two-factor-authentication or change the current secret with the new one. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. totp: type: string pattern: ^[0-9]+$ description: > The one time password shown by the authenticator app. required: - sid - totp responses: '200': description: > The 2FA was activated. Some actions now require the session to be upgraded. Some other actions become eventually available. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user identifier returned by `/user/register`. It is also contained in the user's verification email. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/remove/: post: tags: - Session and User Management summary: Remove 2FA description: > Deactivates two-factor-authentication in the account. Requires the session to be elevated and `/session/challenge` to be called first. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A base64-encoded SHA256-hash of the user's password. required: - sid - password responses: '200': description: > The 2FA was set up and a secret has been generated. The output contains several pieces of information all featuring that particular secret. content: application/json: schema: type: object properties: uid: type: string format: uuid description: > The user id the two-factor-authentication was removed for. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/enabled/: post: tags: - Session and User Management summary: Test 2FA Status description: > A client can test whether two-factor-authentication is enabled for a given email address. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. A device needs to be logged in to the session. email: type: string format: email description: > An email to test whether 2FA is active on it or not required: - sid - email responses: '200': description: > The information on the email address is available. content: application/json: schema: type: object properties: tfa: type: boolean description: > Indication the activation status of two-factor-authorization on the given email-address. required: - tfa '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/resetlost/: post: tags: - Session and User Management summary: Reset Lost 2FA Token description: > This method will deactivate the two-factor-authentication in case an authenticator got lost permanently. A prior call to `/user/tfa/lost` must have succeeded which effectively sent an email to the user containing a code that needs to be provided with the request to this action. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. code: type: string format: byte pattern: ^[0-9]{6}\=$ description: > The code received via email after calling `/user/tfa/lost`. required: - sid - password responses: '200': description: > The two-factor-authentication has been reset and needs to be set up again to gain full functionality again. content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user's identifier returned. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/tfa/setup/: post: tags: - Session and User Management summary: Set up 2FA description: > Adds two-factor-authentication to a user's account and provides a 2FA-secret. Can only be called as long as 2FA is not already established on an account. To activate and therefore eventually establish the 2FA, call `/user/tfa/verify`. The session needs a user to be logged in. Also, a challenge needs to be set up prior to this call by calling `/session/challenge`. The gui should not silently auto-fill the password but actually require the password to be entered manually. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > A base64-encoded SHA256-hash of the user's password. required: - sid - password responses: '200': description: > The 2FA was set up and a secret has been generated. The output contains several pieces of information all featuring that particular secret. content: application/json: schema: type: object properties: setup: description: > Raw properties about the TOTP-calculation. type: object properties: digits: type: integer description: > The number of digits to calculate for a 2FA-code. algorithm: type: string description: > The algorithm to be used for the hash calculation on which the 2FA-generation is based. period: type: integer description: > The number of seconds a TOTP is valid. issuer: type: string description: > The name of the TOTP-issuer. label: type: string description: > The label for the TOTP-item in an authenticator application. account: type: string description: > The user's primary email address to specify the account name. required: - digits - algorithm - period - issuer - label - account secret: type: object description: > An object containing various encodings of the secret. properties: raw: type: string format: byte description: > The actual base64-encoded secret. Please note that for most purposes, a base32-encoding is used when interfacing this value to the user. base64: type: string description: > Same as `raw`, but without a deserialization hint, keeping the base64-string intact. base32: type: string description: > A base32-encoded representation of the secret as is required for many applications. required: - raw - base64 - base32 uri: type: string format: uri description: > The TOTP-URI that can be used in a link or a QR code for fast access to an authenticator application. qrcode: type: object description: > A set of properties defining everything required to draw a QR code without needing to qr-encode the URI on consumer side. properties: size: type: integer description: > The number of modules along each dimension of the QR code. QR codes are actually squares, so only one size value is sufficient. bits: type: string format: byte description: > A base64 representation of the bitmask. Assumed a black on white code, a set bit represents a black module whereas a logical 0 represents a white background module. The bits are stored little-endian in each byte, meaning, the first module in the top left corner is specified by the least significant bit in the first byte. required: - size - bits required: - setup - secret - uri - qrcode '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/email/verify/: post: tags: - Session and User Management summary: Verify Changed Email description: > Verifies the changed email address of an already registered user. No session is required for this action. For verifying an new email address, see `/user/verify`. requestBody: required: true content: application/json: schema: type: object properties: uid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The user identifier returned by `/user/register` or `/user/login`. It will also be contained in the user's verification email. code: type: string pattern: ^[0-9]{6}$ description: > The verification code sent via email to the user's email address. required: - uid - code responses: '200': description: > The email address has been verified. Any existing objects owned by the device are now owned by the user. content: application/json: schema: type: object properties: uid: type: string format: uuid description: > The user's identifier replied. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /user/email/change/: post: tags: - Session and User Management summary: Change User Email description: > Changes a user's primary email address, effectively making it the new login name for subsequent logins. Before the change takes place, the new email needs to be verified as well. A separate 2FA-token is required if 2FA is set up for the user A call to `/user/challenge` is required first to generate a challenge and retrieve the salt for the user. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier returned by `/session/start`. email: type: string format: email description: > The new email address to be registered for the user. password: type: string format: byte pattern: ^[0-9A-Za-z\/\+]{43}\=$ description: > The password for the user in the same way as for `/user/login`. tfa: type: string format: string pattern: ^[0-9]{6}$ description: > If the user has two-factor-authentication enabled, this action requires a valid TOTP key, regardless of the session's elevation status. If the user has no two-factor-authentication set, this parameter can be omitted. required: - sid - email - password responses: '200': description: > The email was changed and a verification email has been sent to the user. The code is valid for 90 minutes. After that, the registration needs to be started again. content: application/json: schema: type: object properties: uid: type: string format: uuid description: > The user's unique id (GUID). required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /session/elevate/: post: tags: - Session and User Management summary: Elevate Session description: > Elevates a session by taking a two-factor-authentication password. If a user is logged in but no two-factor-authentication is set up for the account, the call succeeds automatically. If the call is issued against an already elevated session, it also succeeds automatically. requestBody: content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier to generate a challenge for. totp: type: string pattern: ^[0-9]+$ description: > The one time password shown by the authenticator app. required: - sid - totp responses: '200': description: > The session has been elevated content: application/json: schema: type: object properties: uid: type: string format: byte description: > A base64-encoded representation of the logged-in user. required: - uid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /session/start/: post: tags: - Session and User Management summary: Start a New Session description: > Starts a new session with a given device. Nearly all actions require an active session to be started. requestBody: required: true description: > Needs a device id to tie various objects to the device account. content: application/json: schema: type: object properties: device: type: string format: uuid pattern: ^[0-9a-f]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > A device id representing the device. The device id has to be obtained by calling `/device/register` first. This device id should be stored on the device (e.g. as a cookie) to make objects created by the device's user accessible to them later on. If a device id is lost and the objects have not been tied to a registered user account, they are all lost. version: type: string pattern: ^[0-9]+\.[0-9]{1,3}\.[0-9]{1,3}$ default: 1.0.0 description: > The API version to be used for the session. Defaults to the latest available version. Determines available cipher suites among other parameters. required: - device responses: '200': description: > The request was successful, a session has been established. The user, however, is not authenticated yet. Authentication is performed by calling /session/challenge. In case the email address has not been registered before, see /user/register. content: application/json: schema: type: object properties: sid: type: string format: uuid description: > The unique session id that needs to be issued at subsequent calls to identify the session. salt: type: string format: byte description: > A base64-encoded representation of the salt to be prepended to the password before hashing it. Not the base64-encoded representation shall be used as padding but the raw salt value instead. challenge: type: string format: byte description: > A base64-encoded representation of the HMAC challenge to be used as key for `/device/login`. required: - sid - salt - challenge '400': $ref: '#/components/responses/Error400' '403': $ref: '#/components/responses/Error403' /session/challenge/: post: tags: - Session and User Management summary: Session Challenge description: > Prepares the session for a password authentication, generating a challenge that needs to be used for a password hash calculation. When a challenge is already set up, it will be overwritten by the newly requested one. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier to generate a challenge for. required: - sid responses: '200': description: > A challenge has been calculated and activated in the session. content: application/json: schema: type: object properties: challenge: type: string format: byte description: > A base64-encoded representation of the challenge to be used in the password hash calculation process. salt: type: string format: byte description: > In case a user is logged in to the session, their current base64-encoded salt value is provided. required: - challenge '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' /session/heartbeat/: post: tags: - Session and User Management summary: Keep session alive description: > Send a "no operation" command to the server causing it to reset the session time out. requestBody: required: true content: application/json: schema: type: object properties: sid: type: string format: uuid pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ description: > The session identifier for the session to be kept alive. required: - sid responses: '200': description: > The session timeout has been reset successfully. content: application/json: schema: type: object properties: sid: type: string format: uuid description: > The session identifier returned. required: - sid '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' components: responses: Error401: description: > You are not allowed to perform this action. content: application/json: schema: type: object properties: message: type: string required: - message Error403: description: > The provided information was not suitable for the call. content: application/json: schema: type: object properties: error: type: object properties: message: type: string description: > A description of what went wrong. code: type: integer description: > A unique error code further referencing the nature of the error. This can be used to handle different errors in different ways. The possible error codes returned are subject to the respective action called. required: - message - code required: - error Error400: description: > The content body did not contain valid JSON or did not match the request format. content: application/json: schema: type: object properties: message: type: string required: - message