Auth API v3

{ "openapi": "3.0.2", "info": { "title": "Auth API", "description": "Authorization and authentication API for EXOsoft products (DCI, VM)", "version": "4.0.0", "contact": { "email": "help@ispsystem.com" } }, "servers": [ { "url": "https://my.vepp.com/src/v4" }, { "url": "https://localhost:8080/src/v4" }, { "url": "http://localhost:7000/" } ], "paths": { "/public/roles": { "get": { "deprecated": true, "summary": "Get list of additional role`s names", "description": "It is not so deprecated as experimental. OpenAPI has no property to show this. Basically auth service does not know anything about builtin roles so you have to add them to environment variable BUILTIN_ROLES. For example, it's value could be \"@admin,@user\".", "tags": [ "Permissions" ], "responses": { "200": { "description": "You will recieve the list of the roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string", "example": "@admin_support" } } } } } } } } } }, "/role": { "get": { "summary": "Get list of custom roles", "description": "That handler is used to get full information about all custom roles", "operationId": "GetRoleList", "tags": [ "Role" ], "responses": { "200": { "description": "You wall recieve the list of all existing custom roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Role unique identifier", "example": 1 }, "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "The role data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "post": { "summary": "Create a custom role", "description": "Add a custom role in the system", "operationId": "CreateRole", "tags": [ "Role" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "data" ], "properties": { "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts", "pattern": "^@\\w+" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "Created roles data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } }, "responses": { "201": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/role/{role_id}": { "get": { "summary": "Get information about selected custom role", "description": "This handle returns same information like /role does", "operationId": "GetRole", "tags": [ "Role" ], "parameters": [ { "in": "path", "name": "role_id", "required": true, "description": "Role unique identifier", "schema": { "type": "integer" } } ], "responses": { "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "200": { "description": "The role information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Role unique identifier", "example": 1 }, "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "The role data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } } } }, "post": { "summary": "Edit a custom role", "description": "Edit a existed custom role in the system", "operationId": "EditRole", "tags": [ "Role" ], "parameters": [ { "in": "path", "name": "role_id", "required": true, "description": "Role unique identifier", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "Created roles data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Delete a custom role", "description": "Delete a existed custom role in the system", "operationId": "DeleteRole", "tags": [ "Role" ], "parameters": [ { "in": "path", "name": "role_id", "required": true, "description": "Role unique identifier", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/handles": { "get": { "summary": "Get available handlers for current user", "operationId": "SelfHandles", "tags": [ "Permissions" ], "responses": { "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "200": { "description": "Get available handlers", "content": { "application/json": { "schema": { "type": "object", "properties": { "handles": { "type": "object", "example": { "auth_v4": { "delete": [ "/user/{user_id}" ], "get": [ "/user/{user_id}" ], "post": [ "/user/{user_id}" ] } }, "additionalProperties": true }, "user_id": { "type": "integer", "description": "User unique identifier", "example": 1 } } } } } } } } }, "/self/subroles": { "get": { "summary": "Get current user subroles", "operationId": "SelfSubroles", "tags": [ "Role" ], "responses": { "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "200": { "description": "Get user subroles", "content": { "application/json": { "schema": { "type": "object", "properties": { "subroles": { "type": "array", "description": "List of user subroles", "items": { "type": "string", "example": "@common_read" } }, "user_id": { "type": "integer", "description": "User unique identifier", "example": 1 } } } } } } } } }, "/public/token": { "post": { "summary": "Authenticate user using username and password", "description": "Using this handler you just authenticate user in the system", "operationId": "Auth", "tags": [ "Token" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User name. We are using user E-Mail as login", "example": "admin@example.com" }, "password": { "type": "string", "description": "User password" }, "confirmed": { "type": "boolean", "description": "If token is not confirmed you must confirm it using handle /public/tokan/confirm" } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/token": { "post": { "summary": "Create long life or infinit token", "description": "Such tokens should be used for integration purpose only", "operationId": "PostToken", "tags": [ "Token" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "datetime", "description": "Token exparation date", "example": "2022-01-01 00:00:00" }, "description": { "type": "string", "maxLength": 255, "description": "Any comment you want to add for new token", "example": "Integration with google :)" } }, "required": [ "expires_at" ] } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/token/{token_id}": { "delete": { "summary": "Remove token", "description": "Most tokens has limited lifetime. But if you want to revoke access for some integrated applications or users you can manually remove their tokens", "operationId": "DeleteToken", "tags": [ "Token" ], "security": [ { "Token": [] }, { "Internal": [] } ], "parameters": [ { "in": "path", "name": "token_id", "required": true, "description": "Token id or value", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/su": { "post": { "summary": "Create new token for trustee", "description": "Makes possible to act as specified user. You should be administrator or trustee for this user", "operationId": "UserSu", "tags": [ "Token" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/back": { "post": { "summary": "Get back to trusteee account", "description": "Makes possible to return to previous level after making SU", "operationId": "SelfBack", "tags": [ "Token" ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user": { "get": { "summary": "Get list of the users", "description": "Returns complete list of the users. To limit it you can use standard filtering and pagination query string syntax", "operationId": "UserList", "tags": [ "Users" ], "parameters": [ { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "List field name. Gets set of unique field values. This parameter used to get values for select input in filtering forms. Filtering, pagination and order parameters will be ignored", "example": "state" }, { "in": "query", "name": "where", "schema": { "type": "string" }, "description": "Filtering rules for the list. You can use any list field name and set of logical operations (OR, AND, NOT, EQ(=), NE(<>), GT(>), GE(>=), LT(<), LE(<=) and CP(LIKE)) for making filtering conditions", "example": "id GT 100 AND (name CP 'alex%' OR name CP 'georg')" }, { "in": "query", "name": "orderby", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Sorting rules for the list. You can use any list field name and optional ordering parameter (`ASC` and `DESC`). `ASK` is the default so you needent to specify it", "style": "form", "explode": false, "example": "name, age DESC" }, { "in": "query", "name": "limit", "schema": { "type": "string" }, "description": "Limit row count in result. It consists from one or two parts separeted by ','. First (optional) - offset, sets first row number to return (counting from 1). Second - size, set maximum row count in result", "example": "10,20" }, { "in": "query", "name": "action", "schema": { "type": "string", "enum": [ "select", "save", "delete" ] }, "deprecated": true, "description": "You can save your query params `orderby` and `where` or you can use saved one" } ], "responses": { "200": { "description": "You will recieve the list of the users", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "post": { "summary": "Create new user/administrator", "description": "Register new user in the system. User will not be able to login before he/her will be granted access to some instance", "operationId": "CreateUser", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name", "example": "admin@example.com" }, "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "We save only hash so nobody can read it. But you can restore your password using E-Mail" }, "roles": { "description": "Set of the roles for \"src\" service", "type": "array", "items": { "type": "string" }, "minItems": 1, "default": [ "@user" ] }, "auth_source": { "type": "string", "default": "local", "enum": [ "local", "ldap" ], "description": "Auth source for authentication" }, "email_confirm": { "type": "boolean", "default": false, "description": "Is email confirmed" }, "timezone": { "type": "string", "description": "Custom timezone for current user", "maxLength": 64, "pattern": "^[-A-Za-z0-9]*$", "example": "UTC (any random string)" } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user": { "get": { "summary": "Get list of the instance users", "description": "Returns complete list of the instance users. To limit it you can use standard filtering and pagination query string syntax", "operationId": "InstanceUserList", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "List field name. Gets set of unique field values. This parameter used to get values for select input in filtering forms. Filtering, pagination and order parameters will be ignored", "example": "state" }, { "in": "query", "name": "where", "schema": { "type": "string" }, "description": "Filtering rules for the list. You can use any list field name and set of logical operations (OR, AND, NOT, EQ(=), NE(<>), GT(>), GE(>=), LT(<), LE(<=) and CP(LIKE)) for making filtering conditions", "example": "id GT 100 AND (name CP 'alex%' OR name CP 'georg')" }, { "in": "query", "name": "orderby", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Sorting rules for the list. You can use any list field name and optional ordering parameter (`ASC` and `DESC`). `ASK` is the default so you needent to specify it", "style": "form", "explode": false, "example": "name, age DESC" }, { "in": "query", "name": "limit", "schema": { "type": "string" }, "description": "Limit row count in result. It consists from one or two parts separeted by ','. First (optional) - offset, sets first row number to return (counting from 1). Second - size, set maximum row count in result", "example": "10,20" }, { "in": "query", "name": "action", "schema": { "type": "string", "enum": [ "select", "save", "delete" ] }, "deprecated": true, "description": "You can save your query params `orderby` and `where` or you can use saved one" } ], "responses": { "200": { "description": "You will recieve the list of the instance users", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/password": { "post": { "summary": "Change current user password", "description": "User can change password for himself only if he/she can provide current one. Or he/she can use password recovery procedure and change it via E-Mail", "operationId": "SelfPassword", "tags": [ "Users" ], "security": [ { "Token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "old_password": { "type": "string", "description": "Old user password" }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "New password" } }, "required": [ "password", "old_password" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/password": { "post": { "summary": "Change user password", "description": "Administrator can change password for any user in the system", "operationId": "ChangePassword", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "description": "New password" } }, "required": [ "password" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/lock": { "post": { "summary": "Add blocking dependency", "description": "User with as least one active dependency cannot be deleted", "operationId": "UserLock", "tags": [ "Internal" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "description": "Service name that have made this request" }, "description": { "type": "string", "description": "Description" } }, "required": [ "service", "description" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/lock/{service}": { "delete": { "summary": "Remove blocking dependency", "description": "Release user. Service should call this handler if it have locked this user before and does not need it existence any more", "operationId": "UserUnlock", "tags": [ "Internal" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "service", "required": true, "description": "Service name was used to create blocking dependency", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}": { "post": { "summary": "Edit selected user", "operationId": "EditUser", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "enum": [ "en", "ru" ], "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user", "maxLength": 64, "pattern": "^[-A-Za-z0-9]*$", "example": "UTC (any random string)" } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get user details", "operationId": "GetUser", "description": "Getting user details by user identifier", "deprecated": true, "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "The user details was get successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Completely delete user from the system", "description": "User must not be owner of any instance in system. User can not delete himself", "operationId": "UserDelete", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self": { "post": { "summary": "Edit yourself", "operationId": "EditSelf", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "lang": { "type": "string", "description": "The user interface language", "enum": [ "en", "ru" ], "example": "en" }, "timezone": { "pattern": "^[-_A-Za-z0-9\\/]+$" } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get yourself details", "operationId": "GetSelf", "description": "Getting details about yourself", "tags": [ "Users" ], "responses": { "200": { "description": "The user details was get successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/first_user_invite": { "post": { "summary": "Get first user token", "operationId": "FirtsUserInvite", "tags": [ "Users" ], "security": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "First user token", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "First user token" } } } } } } } } }, "/public/token/{token}/invite_first_user": { "post": { "summary": "Create first user", "operationId": "CreateFirstUser", "tags": [ "Users" ], "security": [], "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string", "format": "token", "minLength": 16, "maxLength": 16, "description": "First user token" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name", "example": "admin@example.com" }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "First user password, we save only hash and nobody can read password" }, "lang": { "type": "string", "description": "The user interface language", "enum": [ "en", "ru" ], "example": "en" } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } } } } }, "/user/{user_id}/acl": { "post": { "summary": "Set users access control list (ACL)", "description": "Sets IPs user allowed to login from", "tags": [ "Acl" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "operationId": "EditUserAcl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get users access control list (ACL)", "description": "Returns set of IPs user allowed to login from", "operationId": "GetUserAcl", "tags": [ "Acl" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "Response format for user ACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/acl": { "post": { "summary": "Set users access control list (ACL)", "description": "Sets IPs user allowed to login from", "tags": [ "Acl" ], "operationId": "SetSelfAcl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get users access control list (ACL)", "description": "Returns set of IPs user allowed to login from", "operationId": "GetSelfAcl", "tags": [ "Acl" ], "responses": { "200": { "description": "Response format for user ACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/global/whoami": { "get": { "summary": "Get your current roles to single instance services", "description": "That handler is used by proxy to check access to single instance services when request contains token", "deprecated": true, "security": [], "parameters": [ { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" } ], "tags": [ "Proxy" ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/instance/{instance_id}/whoami": { "get": { "summary": "Get your current roles on selected instance", "description": "That handler is used by proxy to check access to multi instance services when request contains token", "deprecated": true, "security": [], "parameters": [ { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" }, { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } } ], "tags": [ "Proxy" ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/whoami": { "get": { "summary": "Get your current session information", "description": "That handler is used to check user session", "parameters": [ { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" } ], "tags": [ "Token" ], "responses": { "200": { "description": "THe session information", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "integer", "example": 4 }, "owner_email": { "description": "Authorized owner email. That value will be used to check access for this session.", "type": "string", "example": "user@example.com" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "integer", "example": 3 }, "trustee_email": { "description": "Authorized user email. It contains email of user was used to login to system.", "type": "string", "example": "admin@example.com" }, "roles": { "description": "Current user (owner) roles", "type": "array", "items": { "type": "string", "example": "@user" } } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/import/user": { "post": { "summary": "Create new user/administrator in selected instance", "description": "Register new user in the system and grant access to selected instance. For internal use only. Using simple '/user' handle is more properly way to do it. '/user' handle must be imroved to accept crypted passwords.", "operationId": "InstanceUserImport", "deprecated": true, "tags": [ "Internal" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name" }, "encrypted_password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "It must be an encrypted string. We save it as is." }, "roles": { "description": "Set of the roles for \"src\" service", "type": "array", "items": { "type": "string" }, "minItems": 1 }, "email_confirm": { "type": "boolean", "default": false, "description": "Is email confirmed" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state" } }, "required": [ "email", "encrypted_password", "roles" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user/{user_id}": { "get": { "summary": "Get roles of selected user in selected instance", "operationId": "GetUserPermissions", "description": "That handler is used by proxy to check access to multi instance services when request doesn't contain token but has Internal-Auth header", "deprecated": true, "tags": [ "Proxy" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "post": { "summary": "Grant access to selected instance for selected user", "operationId": "CreateUserPermissions", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Revoke access of selected user to selected instance", "operationId": "RevokeUserPermissions", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user/{user_id}/trustee/{trustee_id}": { "get": { "summary": "Get roles of selected user/trustee pair in selected instance", "operationId": "GetTrusteePermissions", "description": "That handler is used by proxy to check access to multi instance services when request doesn't contain token but has Internal-Auth header", "deprecated": true, "tags": [ "Proxy" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user/{user_id}/trustee/{trustee_id}/roles": { "post": { "summary": "Grant access to selected instance for selected trustee", "operationId": "CreateTrusteePermissions", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1, "default": [ "@user" ] } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Revoke access of selected trustee to selected instance", "operationId": "RevokeTrusteePermissions", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/resume": { "post": { "summary": "Allow user access", "operationId": "UserAccessResume", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/suspend": { "post": { "summary": "Restrict user access", "operationId": "UserAccessSuspend", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/trustee/{trustee_id}": { "get": { "summary": "Get roles of selected user/trustee pair", "operationId": "GetTrustee", "description": "That handler can be used by proxy to check access to single instance services when request doesn't contain token but has Internal-Auth header. But in general it never should be used (we needent to grant trustee access to single instance services because most of such services are used to manipulate personal user settings)", "deprecated": true, "tags": [ "Proxy" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/trustee/{trustee_id}/roles": { "post": { "summary": "Grant access to selected trustee", "operationId": "EditTrustee", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1, "default": [ "@user" ] } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Revoke access of selected trustee", "operationId": "DeleteTrustee", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/global/whoami/method/{method}/target/{target}": { "get": { "summary": "Get your current roles to single instance services", "description": "That handler is used by proxy to check access to single instance services when request contains token", "security": [], "parameters": [ { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "tags": [ "Proxy" ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/instance/{instance_id}/whoami/method/{method}/target/{target}": { "get": { "summary": "Get your current roles on selected instance", "description": "That handler is used by proxy to check access to multi instance services when request contains token", "security": [], "parameters": [ { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" }, { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "tags": [ "Proxy" ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/method/{method}/target/{target}": { "get": { "summary": "Get roles of selected user in single instance services", "description": "That handler is used by proxy to check access to single instance services when request doesn't contain token but has Internal-Auth header", "tags": [ "Proxy" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/trustee/{trustee_id}/method/{method}/target/{target}": { "get": { "summary": "Get roles of selected user/trustee pair", "description": "That handler can be used by proxy to check access to single instance services when request doesn't contain token but has Internal-Auth header. But in general it never should be used (we needent to grant trustee access to single instance services because most of such services are used to manipulate personal user settings)", "tags": [ "Proxy" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user/{user_id}/method/{method}/target/{target}": { "get": { "summary": "Get roles of selected user in selected instance", "description": "That handler is used by proxy to check access to multi instance services when request doesn't contain token but has Internal-Auth header", "tags": [ "Proxy" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/instance/{instance_id}/user/{user_id}/trustee/{trustee_id}/method/{method}/target/{target}": { "get": { "summary": "Get roles of selected user in selected instance", "description": "That handler is used by proxy to check access to multi instance services when request doesn't contain token but has Internal-Auth header", "tags": [ "Proxy" ], "security": [ { "Internal": [] } ], "parameters": [ { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/acl": { "get": { "summary": "Get list of access control lists", "description": "That handler is used to get full information about access control lists were setup on system", "tags": [ "Acl" ], "operationId": "AclList", "deprecated": true, "responses": { "200": { "description": "You wall recieve the list of all existing ACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id" }, "name": { "type": "string", "description": "Unique ACL name" }, "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "description": "Single ip address, network or range" } }, "members": { "type": "array", "items": { "type": "string", "description": "User name" } } } } } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "post": { "summary": "Create new access control list", "description": "Create new one ACL, this handle allows create ACL and add members to it", "tags": [ "Acl" ], "operationId": "CreateAcl", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Unique name" }, "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } }, "members": { "type": "array", "description": "List of ACL members", "items": { "type": "string", "maxLength": 255, "description": "User name or user ID" } } }, "required": [ "name", "ip_list" ] } } } }, "responses": { "201": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/acl/{acl_id}": { "get": { "summary": "Get information about selected ACL", "description": "This handle returns same information like /acl does", "tags": [ "Acl" ], "operationId": "AclInfo", "parameters": [ { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" } ], "deprecated": true, "responses": { "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "200": { "description": "You wall recieve singleACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id" }, "name": { "type": "string", "description": "Unique ACL name" }, "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "description": "Single ip address, network or range" } }, "members": { "type": "array", "items": { "type": "string", "description": "User name" } } } } } } } } }, "post": { "summary": "Modify ACL", "description": "That handler allows to change ACL and manage its members. If members missed they will be unchanged", "tags": [ "Acl" ], "operationId": "EditAcl", "parameters": [ { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" } ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Unique name" }, "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } }, "members": { "type": "array", "description": "List of ACL members", "items": { "type": "string", "maxLength": 255, "description": "User name or user ID" } } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Delete ACL", "description": "Completely remove ACL", "operationId": "DeleteAcl", "tags": [ "Permissions" ], "parameters": [ { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/acl/{acl_id}/user/{user_id}": { "post": { "summary": "Adds ACL member", "description": "That handler is will add and return 201Created if new member was added to ACL or 200Ok if member already exists", "tags": [ "Acl" ], "operationId": "AclAddMember", "parameters": [ { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "deprecated": true, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "201": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Removes ACL member", "description": "That handler will remove member from ACL", "tags": [ "Acl" ], "operationId": "AclRemoveMember", "parameters": [ { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" }, { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "deprecated": true, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/key": { "post": { "summary": "Create key for current user", "description": "Create key that can be used to get token for current user", "tags": [ "Key" ], "security": [ { "Token": [] } ], "operationId": "SelfKey", "responses": { "201": { "description": "New key was successfully made", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New key id. It is needed to match key in database (for debug purpose only)" }, "key": { "type": "string", "description": "New key. It can be used to get security token only. Keys do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/key": { "post": { "summary": "Create key for specified user", "description": "Create key that can be used to get token for selected user", "tags": [ "Key" ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "operationId": "UserKey", "responses": { "201": { "description": "New key was successfully made", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New key id. It is needed to match key in database (for debug purpose only)" }, "key": { "type": "string", "description": "New key. It can be used to get security token only. Keys do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/key": { "post": { "summary": "Use key to get authentication token", "description": "Use key to get authentication token", "tags": [ "Key" ], "security": [], "operationId": "AuthByKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "key was got using /self/key or /user/{user_id}/key handles" } }, "required": [ "key" ] } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/confirmation/{confirmation_id}/change_password": { "post": { "summary": "Change password by confirmation token", "description": "Use confirmation received by mail to change user password", "tags": [ "Users" ], "security": [], "operationId": "ChangePasswordByConfirmation", "parameters": [ { "in": "path", "name": "confirmation_id", "required": true, "description": "Confirmation token for the password restoration", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "description": "New password" } }, "required": [ "password" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/confirmation/{confirmation_id}/invite_user": { "post": { "summary": "Activate invited user by confirmation token", "description": "Use confirmation received by mail to activate user", "tags": [ "Users" ], "security": [], "operationId": "ActivateUserByConfirmation", "parameters": [ { "in": "path", "name": "confirmation_id", "required": true, "description": "Confirmation token for the password restoration", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "description": "User password" }, "lang": { "description": "The user interface language", "type": "string", "enum": [ "en", "ru" ], "default": "en" } }, "required": [ "password" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/2fa": { "post": { "summary": "Setup two factor authorization for current user", "description": "After successful setup you will be forced to confirm your authentication token by secret code before using it", "tags": [ "2FA" ], "security": [ { "Token": [] } ], "operationId": "Setup2FA", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "format": "base32", "description": "It must be a base32 encoded sequence of 40 random bytes", "minLength": 64, "maxLength": 64 }, "code": { "type": "integer", "description": "Valid Multi-Factor verification 6-digit code" } }, "required": [ "secret", "code" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Turn off two factor authorization for current user", "tags": [ "Token" ], "security": [ { "Token": [] } ], "operationId": "Delete2FA", "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/2fa": { "delete": { "summary": "Turn off two factor authorization for selected user", "tags": [ "2FA" ], "security": [ { "Token": [] } ], "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "operationId": "Delete2FA", "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/token/confirm": { "post": { "summary": "Confirm two factor authorization for current token", "description": "If 2FA enable for current user you have to confirm your authorization token by calling this handle to use this token", "tags": [ "2FA" ], "security": [], "operationId": "TokenConfirm", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token that was got using /public/token function" }, "code": { "type": "integer", "description": "Valid Multi-Factor verification 6-digit code" }, "reserve_code": { "type": "string", "description": "Reserve code for token verification" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/public/2fa/qrcode": { "post": { "summary": "Generate Google Authenticator PNG", "description": "It is just generates PNG, no service data will be modified", "tags": [ "2FA" ], "security": [], "operationId": "GetQRCode", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the token in google authenticator" }, "secret": { "type": "string", "format": "base32", "description": "It must be a base32 encoded sequence of 40 random bytes", "minLength": 64, "maxLength": 64 }, "size": { "type": "integer", "minimum": 177, "maximum": 1024, "default": 256 }, "recovery": { "type": "string", "enum": [ "low", "medium", "high", "highest" ], "default": "medium" } }, "required": [ "name", "secret" ] } } } }, "responses": { "200": { "description": "QR code image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } } } } }, "/restrictions/role": { "post": { "summary": "Change restrictions for some role", "description": "Using this handler you can change authentification restrictiction policy for concete roles", "operationId": "ChangeRoleRestrictions", "tags": [ "Restrictions" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attempts_max_count": { "type": "integer", "description": "Maximum number of attempts for some role to get banned", "example": 10, "nullable": true }, "time_to_unban": { "type": "integer", "description": "Which time in seconds, user will be banned", "example": 600 }, "time_between_attempts": { "type": "integer", "description": "Which time in seconds, user shoud wait, after incorrect login.", "example": 1 }, "attempts_counting_duration": { "type": "integer", "description": "Which time in seconds, unseccessful attempts will be counted.", "example": 600 }, "role": { "type": "string", "description": "User role starting with @", "example": "@user" } }, "additionalProperties": false, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get list of role restrictions", "tags": [ "Restrictions" ], "responses": { "200": { "description": "You will recieve the list of the restrictictions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique id of restriction.", "example": 1 }, "attempts_max_count": { "type": "integer", "description": "Maximum number of attempts for some role to get banned", "example": 10, "nullable": true }, "time_to_unban": { "type": "integer", "description": "Which time in seconds, user will be banned", "example": 600 }, "time_between_attempts": { "type": "integer", "description": "Which time in seconds, user shoud wait, after incorrect login.", "example": 1 }, "attempts_counting_duration": { "type": "integer", "description": "Which time in seconds, unseccessful attempts will be counted.", "example": 600 }, "role": { "type": "string", "description": "User role starting with @", "example": "@user" } } } } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/restrictions/ban": { "get": { "summary": "Get the list of banned users", "tags": [ "Restrictions" ], "responses": { "200": { "description": "You will recieve the list of the bans", "content": { "application/json": { "schema": { "type": "object", "properties": { "bans": { "type": "array", "items": { "type": "object", "properties": { "user_ip": { "type": "string", "example": "127.0.0.1", "description": "User IP" }, "user_id": { "type": "number", "example": 3, "description": "User ID" }, "banned_until": { "type": "number", "example": 1663152889, "description": "Time in POSIX format." } } } } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/restrictons/ban/{user_id}/{user_ip}": { "delete": { "summary": "Unban user by user id / user ip.", "tags": [ "Restrictions" ], "parameters": [ { "in": "path", "name": "user_id", "schema": { "type": "integer" }, "description": "Unique id of user.", "example": 1 }, { "in": "path", "name": "user_ip", "schema": { "type": "string" }, "description": "Ip address of user.", "example": "172.31.35.3" } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/restrictons/ban/{ban_id}": { "delete": { "summary": "Unban user by ban id", "tags": [ "Restrictions" ], "parameters": [ { "in": "path", "name": "ban_id", "schema": { "type": "integer" }, "description": "Unique id of ban.", "example": 666 } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "403": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/2fa/reserve/generate": { "post": { "summary": "Generate a set of reserve codes", "description": "Each code can be used once only instead of 2fa code", "tags": [ "2FA" ], "security": [ { "Token": [] } ], "operationId": "GenerateReserveCodes", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "Array of codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/time": { "get": { "summary": "Get current server time", "description": "The handler returns current time of the server (UTC timezone by default, it's controlling by docker container timezone)", "tags": [ "Time" ], "operationId": "Time", "deprecated": true, "responses": { "200": { "description": "Current server time is received", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "current_time": { "type": "string", "description": "Current server time" } } } } } } } } } } } }, "/setting/{name}": { "get": { "summary": "Get global setting", "operationId": "GetSetting", "description": "Getting global setting value by name", "tags": [ "Setting" ], "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Name of the global setting" } ], "responses": { "200": { "description": "The global setting details was get successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique global setting name.", "example": "timezone" }, "valie": { "type": "string", "description": "Value of the setting", "example": "UTC" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "post": { "summary": "Add and edit global setting", "description": "Handler allows add and edit setting with name that controlled by the handler", "tags": [ "Setting" ], "security": [], "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Name of the global setting" } ], "operationId": "SettingName", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[-A-Za-z0-9/]+", "description": "Value of the setting" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Remove global setting", "description": "Removes global setting (only for settings that allowed by handler)", "operationId": "DeleteSetting", "tags": [ "Setting" ], "security": [], "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Name of the global setting" } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/setting/{name}": { "post": { "summary": "Add settings for current user", "description": "Adding settings for current user. This handler is used for Frontend needs. Do not use it if you don't know what you are doing", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "CreateSelfSetting", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "User setting name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User settings", "example": { "columns": [ { "key": "name", "fixed": false, "width": 150 }, { "key": "owner", "fixed": false, "width": 160 }, { "key": "note", "fixed": false, "width": 35 } ], "compact": false } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get current user settings by the setting name", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "GetSelfSetting", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "User setting name" } ], "responses": { "200": { "description": "User settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "User settings data", "nullable": true, "type": "object", "example": { "columns": [ { "key": "name", "fixed": false, "width": 150 }, { "key": "owner", "fixed": false, "width": 160 }, { "key": "note", "fixed": false, "width": 35 } ], "compact": false } } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/sshkey": { "post": { "summary": "Add public SSH key for current user", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "CreateSelfSshkey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Public SSH key parameters for adding", "required": [ "name", "ssh_pub_key" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } }, "responses": { "201": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get current user public SSH keys", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "ListSelfSshkey", "responses": { "200": { "description": "Public SSH keys list", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/self/sshkey/{key_id}": { "post": { "summary": "Edit current user public SSH key", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "EditSelfSshkey", "parameters": [ { "in": "path", "name": "key_id", "required": true, "description": "Public SSH key unique identifier", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Public SSH key parameters for editing", "properties": { "name": { "type": "string", "maxLength": 255, "description": "SSH key name", "example": "My laptop key" } } } } } }, "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "get": { "summary": "Get current user public SSH key", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "GetSelfSshkey", "parameters": [ { "in": "path", "name": "key_id", "required": true, "description": "Public SSH key unique identifier", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Public SSH key information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } }, "delete": { "summary": "Remove current user public SSH key", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "DeleteSshkey", "parameters": [ { "in": "path", "name": "key_id", "required": true, "description": "Public SSH key unique identifier", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } }, "/user/{user_id}/sshkey": { "get": { "summary": "Get provided user public SSH keys", "tags": [ "Users" ], "security": [ { "Token": [] } ], "operationId": "ListUserSshkey", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" } ], "responses": { "200": { "description": "Public SSH keys list", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } } } } }, "400": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "401": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } } } } } }, "components": { "requestBodies": { "EditSetting": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[-A-Za-z0-9/]+", "description": "Value of the setting" } }, "required": [ "value" ] } } } }, "Setup2FA": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "format": "base32", "description": "It must be a base32 encoded sequence of 40 random bytes", "minLength": 64, "maxLength": 64 }, "code": { "type": "integer", "description": "Valid Multi-Factor verification 6-digit code" } }, "required": [ "secret", "code" ] } } } }, "Acl": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "Empty": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "CreateUser": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name", "example": "admin@example.com" }, "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "We save only hash so nobody can read it. But you can restore your password using E-Mail" }, "roles": { "description": "Set of the roles for \"src\" service", "type": "array", "items": { "type": "string" }, "minItems": 1, "default": [ "@user" ] }, "auth_source": { "type": "string", "default": "local", "enum": [ "local", "ldap" ], "description": "Auth source for authentication" }, "email_confirm": { "type": "boolean", "default": false, "description": "Is email confirmed" }, "timezone": { "type": "string", "description": "Custom timezone for current user", "maxLength": 64, "pattern": "^[-A-Za-z0-9]*$", "example": "UTC (any random string)" } }, "required": [ "email" ], "additionalProperties": false } } } }, "CreateFirstUser": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name", "example": "admin@example.com" }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "First user password, we save only hash and nobody can read password" }, "lang": { "type": "string", "description": "The user interface language", "enum": [ "en", "ru" ], "example": "en" } }, "required": [ "email", "password" ] } } } }, "EditSelf": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "lang": { "type": "string", "description": "The user interface language", "enum": [ "en", "ru" ], "example": "en" }, "timezone": { "pattern": "^[-_A-Za-z0-9\\/]+$" } } } } } }, "EditUser": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "enum": [ "en", "ru" ], "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user", "maxLength": 64, "pattern": "^[-A-Za-z0-9]*$", "example": "UTC (any random string)" } } } } } }, "InstanceUserImport": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "description": "User E-Mail will be used as login name" }, "encrypted_password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "description": "It must be an encrypted string. We save it as is." }, "roles": { "description": "Set of the roles for \"src\" service", "type": "array", "items": { "type": "string" }, "minItems": 1 }, "email_confirm": { "type": "boolean", "default": false, "description": "Is email confirmed" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state" } }, "required": [ "email", "encrypted_password", "roles" ], "additionalProperties": false } } } }, "ChangePasswordByConfirmation": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "description": "New password" } }, "required": [ "password" ], "additionalProperties": false } } } }, "ActivateUserByConfirmation": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "description": "User password" }, "lang": { "description": "The user interface language", "type": "string", "enum": [ "en", "ru" ], "default": "en" } }, "required": [ "password" ], "additionalProperties": false } } } }, "GetQRCode": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the token in google authenticator" }, "secret": { "type": "string", "format": "base32", "description": "It must be a base32 encoded sequence of 40 random bytes", "minLength": 64, "maxLength": 64 }, "size": { "type": "integer", "minimum": 177, "maximum": 1024, "default": 256 }, "recovery": { "type": "string", "enum": [ "low", "medium", "high", "highest" ], "default": "medium" } }, "required": [ "name", "secret" ] } } } }, "TokenConfirm": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token that was got using /public/token function" }, "code": { "type": "integer", "description": "Valid Multi-Factor verification 6-digit code" }, "reserve_code": { "type": "string", "description": "Reserve code for token verification" } }, "required": [ "token" ] } } } }, "Restriction": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attempts_max_count": { "type": "integer", "description": "Maximum number of attempts for some role to get banned", "example": 10, "nullable": true }, "time_to_unban": { "type": "integer", "description": "Which time in seconds, user will be banned", "example": 600 }, "time_between_attempts": { "type": "integer", "description": "Which time in seconds, user shoud wait, after incorrect login.", "example": 1 }, "attempts_counting_duration": { "type": "integer", "description": "Which time in seconds, unseccessful attempts will be counted.", "example": 600 }, "role": { "type": "string", "description": "User role starting with @", "example": "@user" } }, "additionalProperties": false, "required": [ "role" ] } } } }, "CreateSelfSetting": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User settings", "example": { "columns": [ { "key": "name", "fixed": false, "width": 150 }, { "key": "owner", "fixed": false, "width": 160 }, { "key": "note", "fixed": false, "width": 35 } ], "compact": false } } } } }, "CreateSelfSshkey": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Public SSH key parameters for adding", "required": [ "name", "ssh_pub_key" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } }, "EditSelfSshkey": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Public SSH key parameters for editing", "properties": { "name": { "type": "string", "maxLength": 255, "description": "SSH key name", "example": "My laptop key" } } } } } }, "CreateRole": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "data" ], "properties": { "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts", "pattern": "^@\\w+" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "Created roles data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } }, "EditRole": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "Created roles data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } } }, "responses": { "200Acl": { "description": "Response format for user ACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "example": "192.168.0.0/16" } } }, "required": [ "ip_list" ] } } } }, "200Ok": { "description": "Request complete successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "200InternalWhoami": { "description": "Response format for proxy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "number" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "number" }, "roles": { "nullable": true, "description": "Current users roles. If it is null - no handle was found (no one role was permitted to call it)", "type": "array", "items": { "type": "string" } } }, "required": [ "roles" ] } } } }, "200Whoami": { "description": "THe session information", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "description": "Authorized owner. That value will be used to check access for this session.", "type": "integer", "example": 4 }, "owner_email": { "description": "Authorized owner email. That value will be used to check access for this session.", "type": "string", "example": "user@example.com" }, "trustee_id": { "description": "Authorized user. It contains ID of user was used to login to system. owner_id and trustee_id pair identifies list of current session roles. If owner and trustee is a same user this property can be omitted", "type": "integer", "example": 3 }, "trustee_email": { "description": "Authorized user email. It contains email of user was used to login to system.", "type": "string", "example": "admin@example.com" }, "roles": { "description": "Current user (owner) roles", "type": "array", "items": { "type": "string", "example": "@user" } } } } } } }, "200InstanceUserList": { "description": "You will recieve the list of the instance users", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } } } } }, "200UserGet": { "description": "The user details was get successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } } } } }, "200SettingGet": { "description": "The global setting details was get successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique global setting name.", "example": "timezone" }, "valie": { "type": "string", "description": "Value of the setting", "example": "UTC" } } } } } }, "200Bans": { "description": "You will recieve the list of the bans", "content": { "application/json": { "schema": { "type": "object", "properties": { "bans": { "type": "array", "items": { "type": "object", "properties": { "user_ip": { "type": "string", "example": "127.0.0.1", "description": "User IP" }, "user_id": { "type": "number", "example": 3, "description": "User ID" }, "banned_until": { "type": "number", "example": 1663152889, "description": "Time in POSIX format." } } } } } } } } }, "200Restrictions": { "description": "You will recieve the list of the restrictictions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique id of restriction.", "example": 1 }, "attempts_max_count": { "type": "integer", "description": "Maximum number of attempts for some role to get banned", "example": 10, "nullable": true }, "time_to_unban": { "type": "integer", "description": "Which time in seconds, user will be banned", "example": 600 }, "time_between_attempts": { "type": "integer", "description": "Which time in seconds, user shoud wait, after incorrect login.", "example": 1 }, "attempts_counting_duration": { "type": "integer", "description": "Which time in seconds, unseccessful attempts will be counted.", "example": 600 }, "role": { "type": "string", "description": "User role starting with @", "example": "@user" } } } } } } }, "200Token": { "description": "First user token", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "First user token" } } } } } }, "201Token": { "description": "New token was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New token id. It can be used only for deletion" }, "token": { "type": "string", "description": "New token. It should be used as security token for all other requests. Tokens do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" }, "expires_at": { "type": "string", "nullable": true, "description": "End of the token lifetime", "example": "2023-03-17 12:00:00" }, "confirmed": { "type": "boolean", "example": true, "description": "The user has to be validated by 2FA" } } } } } }, "201Key": { "description": "New key was successfully made", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "New key id. It is needed to match key in database (for debug purpose only)" }, "key": { "type": "string", "description": "New key. It can be used to get security token only. Keys do not saved in database as plaintext and can not be recovered if you lose it. You will have to make new one" } } } } } }, "401Unauthorized": { "description": "Provided token was incorrect or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403Forbidden": { "description": "Current user have no rights to call this handler or view selected object properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "403IpForbidden": { "description": "Current user does not allowed to access using current IP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "404NotFound": { "description": "Required object does not exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } } } } }, "400BadRequest": { "description": "Provided parameters does not match with schema", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, { "properties": { "field": { "type": "string", "description": "Field name that have filed the check" } } } ] } } } }, "201Created": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique object id" }, "task": { "type": "string", "description": "Task id. Most objects are not created immedeatly. In most cases when you recieve result only record in database was created. To finish object creation system will create 'task'. Only when task will be finished object will be ready. You can wait task using its Id or watching for object itself (it is prefered way). For details you should read Notifier documentation" } }, "required": [ "id" ] } } } }, "201SettingCreated": { "description": "Required object was created", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique global setting name" } } } } } }, "200SelfSetting": { "description": "User settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "User settings data", "nullable": true, "type": "object", "example": { "columns": [ { "key": "name", "fixed": false, "width": 150 }, { "key": "owner", "fixed": false, "width": 160 }, { "key": "note", "fixed": false, "width": 35 } ], "compact": false } } } } } } }, "200ListSshkey": { "description": "Public SSH keys list", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } } } } }, "200GetSshkey": { "description": "Public SSH key information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } } } }, "200RoleList": { "description": "You wall recieve the list of all existing custom roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Role unique identifier", "example": 1 }, "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "The role data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } } } } } } } }, "200HandlesGet": { "description": "Get available handlers", "content": { "application/json": { "schema": { "type": "object", "properties": { "handles": { "type": "object", "example": { "auth_v4": { "delete": [ "/user/{user_id}" ], "get": [ "/user/{user_id}" ], "post": [ "/user/{user_id}" ] } }, "additionalProperties": true }, "user_id": { "type": "integer", "description": "User unique identifier", "example": 1 } } } } } }, "200SubRolesGet": { "description": "Get user subroles", "content": { "application/json": { "schema": { "type": "object", "properties": { "subroles": { "type": "array", "description": "List of user subroles", "items": { "type": "string", "example": "@common_read" } }, "user_id": { "type": "integer", "description": "User unique identifier", "example": 1 } } } } } } }, "schemas": { "AclGet": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id" }, "name": { "type": "string", "description": "Unique ACL name" }, "ip_list": { "type": "array", "items": { "type": "string", "format": "iprange", "description": "Single ip address, network or range" } }, "members": { "type": "array", "items": { "type": "string", "description": "User name" } } } }, "GetRole": { "type": "object", "properties": { "id": { "type": "integer", "description": "Role unique identifier", "example": 1 }, "name": { "type": "string", "description": "Role name for inner usage", "example": "@admin_accounts" }, "human_name": { "type": "string", "description": "Role name for human beings", "example": "Admin of accounts" }, "human_descr": { "type": "string", "description": "Role description for human beings", "example": "Such admins could create new users" }, "data": { "type": "object", "description": "The role data", "properties": { "GET": { "type": "array", "items": { "type": "string", "example": "@common_read" } }, "POST": { "type": "array", "items": { "type": "string", "example": "@common_write" } }, "DELETE": { "type": "array", "items": { "type": "string", "example": "@common_write" } } } } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error description on english" }, "code": { "type": "integer", "description": "Error code. It was designed to be unique for each place where an error can occur" } } }, "GetFirstUserToken": { "type": "object", "properties": { "token": { "type": "string", "description": "First user token" } } }, "Restriction": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique id of restriction.", "example": 1 }, "attempts_max_count": { "type": "integer", "description": "Maximum number of attempts for some role to get banned", "example": 10, "nullable": true }, "time_to_unban": { "type": "integer", "description": "Which time in seconds, user will be banned", "example": 600 }, "time_between_attempts": { "type": "integer", "description": "Which time in seconds, user shoud wait, after incorrect login.", "example": 1 }, "attempts_counting_duration": { "type": "integer", "description": "Which time in seconds, unseccessful attempts will be counted.", "example": 600 }, "role": { "type": "string", "description": "User role starting with @", "example": "@user" } } }, "Bans": { "type": "object", "properties": { "bans": { "type": "array", "items": { "type": "object", "properties": { "user_ip": { "type": "string", "example": "127.0.0.1", "description": "User IP" }, "user_id": { "type": "number", "example": 3, "description": "User ID" }, "banned_until": { "type": "number", "example": 1663152889, "description": "Time in POSIX format." } } } } } }, "UserGet": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique internal user Id", "example": 1 }, "uuid": { "type": "string", "description": "Unique user Id. It should be used for all external links", "example": "295cfef4-5eb4-4bb5-aea7-24c6d6990648" }, "email": { "type": "string", "description": "User E-Mail. It is also used as login name", "example": "user@example.com" }, "full_name": { "type": "string", "description": "User first and last name", "example": "John Smith" }, "roles": { "type": "array", "items": { "type": "string", "description": "Role name", "example": "@user" }, "description": "User roles for 'src' service" }, "state": { "type": "string", "enum": [ "active", "disabled" ], "description": "User state", "example": "active" }, "auth_source": { "type": "string", "enum": [ "local", "ldap" ], "description": "Auth source for authentication", "example": "local" }, "email_confirm": { "type": "boolean", "description": "Is email confirmed" }, "lang": { "description": "The user interface language", "type": "string", "example": "en" }, "timezone": { "type": "string", "description": "Custom timezone for current user" } } }, "SettingGet": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique global setting name.", "example": "timezone" }, "valie": { "type": "string", "description": "Value of the setting", "example": "UTC" } } }, "Time": { "type": "object", "properties": { "current_time": { "type": "string", "description": "Current server time" } } }, "SettingValuePattern": { "pattern": "^[-_A-Za-z0-9\\/]+$" }, "Sshkey": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public SSH key unique identifier", "example": 1 }, "name": { "type": "string", "description": "Public SSH key name", "example": "My laptop key" }, "ssh_pub_key": { "type": "string", "format": "sshkey", "description": "Public SSH key", "example": "ssh-rsa XXXXXXX my@laptop.local" } } } }, "securitySchemes": { "Token": { "type": "apiKey", "in": "header", "name": "X-XSRF-Token", "description": "Token. See `POST /token` or `POST /public/token`" }, "Internal": { "type": "apiKey", "in": "header", "name": "Internal-Auth", "description": "Internal-Auth header should contain complete response body from `/whoami` handler. If service recieve such header in request it does not check cookie. No one request coming from outside can contain Internal-Auth header even if it does header will be removed by incoming proxy service. Also this header can have value 'on' means that it is internal system request with `@internal` role access" } }, "parameters": { "Method": { "in": "path", "name": "method", "required": true, "schema": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] } }, "Target": { "in": "path", "name": "target", "required": true, "schema": { "type": "string" } }, "Token": { "in": "header", "name": "X-XSRF-Token", "required": true, "schema": { "type": "string" }, "description": "Token that was got" }, "UserId": { "in": "path", "name": "user_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use user Id or user E-Mail" }, "FirstUserToken": { "in": "path", "name": "token", "required": true, "schema": { "type": "string", "format": "token", "minLength": 16, "maxLength": 16, "description": "First user token" } }, "AclId": { "in": "path", "name": "acl_id", "required": true, "schema": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "number" } ] }, "description": "You can use ACL Id or ACL name" }, "TrusteeId": { "in": "path", "name": "trustee_id", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "number" } ] }, "description": "Trustee - user who was granted with additiobal access by some other user. Trustee always used with user_id (so called owner id). That value will be used to check objects owner if needed. As in `UserId` you can use user Id or user E-Mail for this value." }, "InstanceId": { "in": "path", "name": "instance_id", "required": true, "description": "Existing instance ID. Minimal value - 1.", "schema": { "type": "number" } }, "ConfirmationId": { "in": "path", "name": "confirmation_id", "required": true, "description": "Confirmation token for the password restoration", "schema": { "type": "string", "maxLength": 255 } }, "ListFilter": { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "List field name. Gets set of unique field values. This parameter used to get values for select input in filtering forms. Filtering, pagination and order parameters will be ignored", "example": "state" }, "ListWhere": { "in": "query", "name": "where", "schema": { "type": "string" }, "description": "Filtering rules for the list. You can use any list field name and set of logical operations (OR, AND, NOT, EQ(=), NE(<>), GT(>), GE(>=), LT(<), LE(<=) and CP(LIKE)) for making filtering conditions", "example": "id GT 100 AND (name CP 'alex%' OR name CP 'georg')" }, "ListOrderBy": { "in": "query", "name": "orderby", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Sorting rules for the list. You can use any list field name and optional ordering parameter (`ASC` and `DESC`). `ASK` is the default so you needent to specify it", "style": "form", "explode": false, "example": "name, age DESC" }, "ListLimit": { "in": "query", "name": "limit", "schema": { "type": "string" }, "description": "Limit row count in result. It consists from one or two parts separeted by ','. First (optional) - offset, sets first row number to return (counting from 1). Second - size, set maximum row count in result", "example": "10,20" }, "ListAction": { "in": "query", "name": "action", "schema": { "type": "string", "enum": [ "select", "save", "delete" ] }, "deprecated": true, "description": "You can save your query params `orderby` and `where` or you can use saved one" }, "SettingName": { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Name of the global setting" }, "UserSettingName": { "in": "path", "name": "name", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "User setting name" }, "SshKeyId": { "in": "path", "name": "key_id", "required": true, "description": "Public SSH key unique identifier", "schema": { "type": "integer" } }, "RoleId": { "in": "path", "name": "role_id", "required": true, "description": "Role unique identifier", "schema": { "type": "integer" } } } }, "tags": [ { "name": "Token", "description": "authentication tokens management" }, { "name": "Users", "description": "user management handles" }, { "name": "Internal", "description": "handles for internal use only" }, { "name": "Proxy", "description": "set of handles disigned for proxy to check request credentials" }, { "name": "Permissions", "description": "user roles management" }, { "name": "Acl", "description": "access control lists management" }, { "name": "Key", "description": "keys that can be used once to get authentication token" }, { "name": "2FA", "description": "set of handles to setup and use two factot authentication" }, { "name": "Time", "description": "time, date and timezones operations" }, { "name": "Setting", "description": "global settings management" }, { "name": "Role", "description": "custom roles management" } ], "security": [ { "Token": [] }, { "Internal": [] } ]}