Auth API v4
{
"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://localhost/auth/v4/"
},
],
"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 receive 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": {
"$ref": "#/components/responses/200RoleList"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
},
"post": {
"summary": "Create a custom role",
"description": "Add a custom role in the system",
"operationId": "CreateRole",
"tags": [
"Role"
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateRole"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Created"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/RoleId"
}
],
"responses": {
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"200": {
"description": "The role information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetRole"
}
}
}
}
}
},
"post": {
"summary": "Edit a custom role",
"description": "Edit a existed custom role in the system",
"operationId": "EditRole",
"tags": [
"Role"
],
"parameters": [
{
"$ref": "#/components/parameters/RoleId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/EditRole"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
},
"delete": {
"summary": "Delete a custom role",
"description": "Delete a existed custom role in the system",
"operationId": "DeleteRole",
"tags": [
"Role"
],
"parameters": [
{
"$ref": "#/components/parameters/RoleId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/self/handles": {
"get": {
"summary": "Get available handlers for current user",
"operationId": "SelfHandles",
"tags": [
"Permissions"
],
"responses": {
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"200": {
"$ref": "#/components/responses/200HandlesGet"
}
}
}
},
"/self/subroles": {
"get": {
"summary": "Get current user subroles",
"operationId": "SelfSubroles",
"tags": [
"Role"
],
"responses": {
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"200": {
"$ref": "#/components/responses/200SubRolesGet"
}
}
}
},
"/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/token/confirm"
}
},
"required": [
"email",
"password"
]
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/token": {
"post": {
"summary": "Create long life or infinite 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 expiration 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": {
"$ref": "#/components/responses/201Token"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/self/back": {
"post": {
"summary": "Get back to trustee account",
"description": "Makes possible to return to previous level after making SU",
"operationId": "SelfBack",
"tags": [
"Token"
],
"requestBody": {
"$ref": "#/components/requestBodies/Empty"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/ListFilter"
},
{
"$ref": "#/components/parameters/ListWhere"
},
{
"$ref": "#/components/parameters/ListOrderBy"
},
{
"$ref": "#/components/parameters/ListLimit"
},
{
"$ref": "#/components/parameters/ListAction"
}
],
"responses": {
"200": {
"description": "You will receive the list of the users",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserGet"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
},
"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": {
"$ref": "#/components/requestBodies/CreateUser"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Created"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/ListFilter"
},
{
"$ref": "#/components/parameters/ListWhere"
},
{
"$ref": "#/components/parameters/ListOrderBy"
},
{
"$ref": "#/components/parameters/ListLimit"
},
{
"$ref": "#/components/parameters/ListAction"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InstanceUserList"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"password": {
"type": "string",
"format": "password",
"minLength": 8,
"description": "New password"
}
},
"required": [
"password"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
}
],
"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": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
},
{
"in": "path",
"name": "service",
"required": true,
"description": "Service name was used to create blocking dependency",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/user/{user_id}": {
"post": {
"summary": "Edit selected user",
"operationId": "EditUser",
"tags": [
"Users"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/EditUser"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"get": {
"summary": "Get user details",
"operationId": "GetUser",
"description": "Getting user details by user identifier",
"deprecated": true,
"tags": [
"Users"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200UserGet"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"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": [
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/self": {
"post": {
"summary": "Edit yourself",
"operationId": "EditSelf",
"tags": [
"Users"
],
"requestBody": {
"$ref": "#/components/requestBodies/EditSelf"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
},
"get": {
"summary": "Get yourself details",
"operationId": "GetSelf",
"description": "Getting details about yourself",
"tags": [
"Users"
],
"responses": {
"200": {
"$ref": "#/components/responses/200UserGet"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/public/first_user_invite": {
"post": {
"summary": "Get first user token",
"operationId": "FirtsUserInvite",
"tags": [
"Users"
],
"security": [],
"requestBody": {
"$ref": "#/components/requestBodies/Empty"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Token"
}
}
}
},
"/public/token/{token}/invite_first_user": {
"post": {
"summary": "Create first user",
"operationId": "CreateFirstUser",
"tags": [
"Users"
],
"security": [],
"parameters": [
{
"$ref": "#/components/parameters/FirstUserToken"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateFirstUser"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
}
}
}
},
"/user/{user_id}/acl": {
"post": {
"summary": "Set users access control list (ACL)",
"description": "Sets IPs user allowed to login from",
"tags": [
"Acl"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"operationId": "EditUserAcl",
"requestBody": {
"$ref": "#/components/requestBodies/Acl"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"get": {
"summary": "Get users access control list (ACL)",
"description": "Returns set of IPs user allowed to login from",
"operationId": "GetUserAcl",
"tags": [
"Acl"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Acl"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/self/acl": {
"post": {
"summary": "Set users access control list (ACL)",
"description": "Sets IPs user allowed to login from",
"tags": [
"Acl"
],
"operationId": "SetSelfAcl",
"requestBody": {
"$ref": "#/components/requestBodies/Acl"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
},
"get": {
"summary": "Get users access control list (ACL)",
"description": "Returns set of IPs user allowed to login from",
"operationId": "GetSelfAcl",
"tags": [
"Acl"
],
"responses": {
"200": {
"$ref": "#/components/responses/200Acl"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/Token"
}
],
"tags": [
"Proxy"
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/Token"
},
{
"$ref": "#/components/parameters/InstanceId"
}
],
"tags": [
"Proxy"
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/whoami": {
"get": {
"summary": "Get your current session information",
"description": "That handler is used to check user session",
"parameters": [
{
"$ref": "#/components/parameters/Token"
}
],
"tags": [
"Token"
],
"responses": {
"200": {
"$ref": "#/components/responses/200Whoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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 improved to accept encrypted passwords.",
"operationId": "InstanceUserImport",
"deprecated": true,
"tags": [
"Internal"
],
"security": [
{
"Internal": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/InstanceUserImport"
},
"responses": {
"200": {
"$ref": "#/components/responses/201Created"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/import/user": {
"post": {
"summary": "Create new user/administrator in global environment",
"description": "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": "GlobalUserImport",
"deprecated": true,
"tags": [
"Internal"
],
"security": [
{
"Internal": []
}
],
"requestBody": {
"$ref": "#/components/requestBodies/InstanceUserImport"
},
"responses": {
"200": {
"$ref": "#/components/responses/201Created"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"post": {
"summary": "Grant access to selected instance for selected user",
"operationId": "CreateUserPermissions",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Revoke access of selected user to selected instance",
"operationId": "RevokeUserPermissions",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"default": [
"@user"
]
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Revoke access of selected trustee to selected instance",
"operationId": "RevokeTrusteePermissions",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/user/{user_id}/resume": {
"post": {
"summary": "Allow user access",
"operationId": "UserAccessResume",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/Empty"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/user/{user_id}/suspend": {
"post": {
"summary": "Restrict user access",
"operationId": "UserAccessSuspend",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/Empty"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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 don't need 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": [
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/user/{user_id}/trustee/{trustee_id}/roles": {
"post": {
"summary": "Grant access to selected trustee",
"operationId": "EditTrustee",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"default": [
"@user"
]
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Revoke access of selected trustee",
"operationId": "DeleteTrustee",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/Token"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"tags": [
"Proxy"
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/Token"
},
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"tags": [
"Proxy"
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/UserId"
},
{
"$ref": "#/components/parameters/TrusteeId"
},
{
"$ref": "#/components/parameters/Method"
},
{
"$ref": "#/components/parameters/Target"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200InternalWhoami"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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 will receive the list of all existing ACLs",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AclGet"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
},
"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": {
"$ref": "#/components/responses/201Created"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/acl/{acl_id}": {
"get": {
"summary": "Get information about selected ACL",
"description": "This handle returns same information like /acl does",
"tags": [
"Acl"
],
"operationId": "AclInfo",
"parameters": [
{
"$ref": "#/components/parameters/AclId"
}
],
"deprecated": true,
"responses": {
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"200": {
"description": "You will receive single ACL",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AclGet"
}
}
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/AclId"
}
],
"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": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Delete ACL",
"description": "Completely remove ACL",
"operationId": "DeleteAcl",
"tags": [
"Permissions"
],
"parameters": [
{
"$ref": "#/components/parameters/AclId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/AclId"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"deprecated": true,
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"201": {
"$ref": "#/components/responses/201Created"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Removes ACL member",
"description": "That handler will remove member from ACL",
"tags": [
"Acl"
],
"operationId": "AclRemoveMember",
"parameters": [
{
"$ref": "#/components/parameters/AclId"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"deprecated": true,
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": {
"$ref": "#/components/responses/201Key"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserId"
}
],
"operationId": "UserKey",
"responses": {
"201": {
"$ref": "#/components/responses/201Key"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": {
"$ref": "#/components/responses/201Token"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/public/recovery_password": {
"post": {
"summary": "Recovery user password by email",
"description": "Generate confirmation token and send to user email",
"tags": [
"Users"
],
"security": [],
"operationId": "ResetPassword",
"requestBody": {
"$ref": "#/components/requestBodies/ResetPassword"
},
"responses": {
"200": {
"$ref": "#/components/responses/200EmailSent"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/ConfirmationId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/ChangePasswordByConfirmation"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/ConfirmationId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/ActivateUserByConfirmation"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Token"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/user/{user_id}/confirmation_id": {
"post": {
"summary": "Generate new confirmation token for user",
"description": "Generate new confirmation token for user with user_id. For internal use only.",
"tags": [
"Internal"
],
"security": [
{
"Internal": []
}
],
"operationId": "UserConfirmationToken",
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/Empty"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Created"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": {
"$ref": "#/components/requestBodies/Setup2FA"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
},
"delete": {
"summary": "Turn off two factor authorization for current user",
"tags": [
"Token"
],
"security": [
{
"Token": []
}
],
"operationId": "Delete2FA",
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/user/{user_id}/2fa": {
"delete": {
"summary": "Turn off two factor authorization for selected user",
"tags": [
"2FA"
],
"security": [
{
"Token": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"operationId": "Delete2FA",
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/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": {
"$ref": "#/components/requestBodies/TokenConfirm"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
}
}
}
},
"/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": {
"$ref": "#/components/requestBodies/GetQRCode"
},
"responses": {
"200": {
"description": "QR code image",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
}
}
}
},
"/restrictions/role": {
"post": {
"summary": "Change restrictions for some role",
"description": "Using this handler you can change authentification restrictiction policy for specific roles",
"operationId": "ChangeRoleRestrictions",
"tags": [
"Restrictions"
],
"security": [],
"requestBody": {
"$ref": "#/components/requestBodies/Restriction"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
},
"get": {
"summary": "Get list of role restrictions",
"tags": [
"Restrictions"
],
"responses": {
"200": {
"$ref": "#/components/responses/200Restrictions"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/restrictions/ban": {
"get": {
"summary": "Get the list of banned users",
"tags": [
"Restrictions"
],
"responses": {
"200": {
"$ref": "#/components/responses/200Bans"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
}
}
}
},
"/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": {
"$ref": "#/components/responses/200Ok"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": {
"$ref": "#/components/responses/200Ok"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": {
"$ref": "#/components/requestBodies/Empty"
},
"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": {
"$ref": "#/components/schemas/Time"
}
}
}
}
}
}
}
}
}
},
"/setting/{name}": {
"get": {
"summary": "Get global setting",
"operationId": "GetSetting",
"description": "Getting global setting value by name",
"tags": [
"Setting"
],
"parameters": [
{
"$ref": "#/components/parameters/SettingName"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200SettingGet"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"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": [
{
"$ref": "#/components/parameters/SettingName"
}
],
"operationId": "SettingName",
"requestBody": {
"$ref": "#/components/requestBodies/EditSetting"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
},
"delete": {
"summary": "Remove global setting",
"description": "Removes global setting (only for settings that allowed by handler)",
"operationId": "DeleteSetting",
"tags": [
"Setting"
],
"security": [],
"parameters": [
{
"$ref": "#/components/parameters/SettingName"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
}
}
}
},
"/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": [
{
"$ref": "#/components/parameters/UserSettingName"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateSelfSetting"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
},
"get": {
"summary": "Get current user settings by the setting name",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "GetSelfSetting",
"parameters": [
{
"$ref": "#/components/parameters/UserSettingName"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200SelfSetting"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/self/sshkey": {
"post": {
"summary": "Add public SSH key for current user",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "CreateSelfSshkey",
"requestBody": {
"$ref": "#/components/requestBodies/CreateSelfSshkey"
},
"responses": {
"201": {
"$ref": "#/components/responses/201Created"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
},
"get": {
"summary": "Get current user public SSH keys",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "ListSelfSshkey",
"responses": {
"200": {
"$ref": "#/components/responses/200ListSshkey"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/self/sshkey/{key_id}": {
"post": {
"summary": "Edit current user public SSH key",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "EditSelfSshkey",
"parameters": [
{
"$ref": "#/components/parameters/SshKeyId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/EditSelfSshkey"
},
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
},
"get": {
"summary": "Get current user public SSH key",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "GetSelfSshkey",
"parameters": [
{
"$ref": "#/components/parameters/SshKeyId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200GetSshkey"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
},
"delete": {
"summary": "Remove current user public SSH key",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "DeleteSshkey",
"parameters": [
{
"$ref": "#/components/parameters/SshKeyId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200Ok"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
},
"/user/{user_id}/sshkey": {
"get": {
"summary": "Get provided user public SSH keys",
"tags": [
"Users"
],
"security": [
{
"Token": []
}
],
"operationId": "ListUserSshkey",
"parameters": [
{
"$ref": "#/components/parameters/UserId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/200ListSshkey"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403IpForbidden"
}
}
}
}
},
"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": {
"type": "string",
"description": "Custom timezone for current user",
"maxLength": 64,
"$ref": "#/components/schemas/SettingValuePattern",
"example": "UTC (any random string)"
}
}
}
}
}
},
"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
}
}
}
},
"ResetPassword": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "User E-Mail",
"example": "admin@example.com"
},
"product": {
"type": "string",
"description": "Product name",
"example": "vm"
}
},
"required": [
"email",
"product"
],
"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": "Time in seconds, for how long user should wait, after incorrect login.",
"example": 1
},
"attempts_counting_duration": {
"type": "integer",
"description": "Specifies TTL (in seconds) for login attempts (e.g. after some time attempts will be reset to 0)",
"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 receive the list of the instance users",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserGet"
}
}
}
}
}
}
},
"200UserGet": {
"description": "The user details was get successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserGet"
}
}
}
},
"200SettingGet": {
"description": "The global setting details was get successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingGet"
}
}
}
},
"200Bans": {
"description": "You will receive the list of the bans",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bans"
}
}
}
},
"200Restrictions": {
"description": "You will receive the list of the restrictictions",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Restriction"
}
}
}
}
},
"200Token": {
"description": "First user token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetFirstUserToken"
}
}
}
},
"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": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403Forbidden": {
"description": "Current user have no rights to call this handler or view selected object properties",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403IpForbidden": {
"description": "Current user does not allowed to access using current IP",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404NotFound": {
"description": "Required object does not exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400BadRequest": {
"description": "Provided parameters does not match with schema",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"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 immediately. In most cases when you receive 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 preferred 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": {
"$ref": "#/components/schemas/Sshkey"
}
}
}
}
}
}
},
"200GetSshkey": {
"description": "Public SSH key information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Sshkey"
}
}
}
},
"200RoleList": {
"description": "You will receive the list of all existing custom roles",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GetRole"
}
}
}
}
}
}
},
"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
}
}
}
}
}
},
"200EmailSent": {
"description": "Email sent",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"wait": {
"type": "number",
"description": "Email resend counter, in seconds",
"example": 300
}
}
}
}
}
}
},
"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": "Time in seconds, for how long user should wait, after incorrect login.",
"example": 1
},
"attempts_counting_duration": {
"type": "integer",
"description": "Specifies TTL (in seconds) for login attempts (e.g. after some time attempts will be reset to 0)",
"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 a service receives 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 an additional 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 optionally ordering parameter (`ASC` and `DESC`). `ASC` is the default so you don't need to explicitly specify it",
"style": "form",
"explode": false,
"example": "name, age DESC"
},
"ListLimit": {
"in": "query",
"name": "limit",
"schema": {
"type": "string"
},
"description": "Limits row count in result. It consists from one or two parts separated 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 designed 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 factor authentication (2FA)"
},
{
"name": "Time",
"description": "time, date and timezones operations"
},
{
"name": "Setting",
"description": "global settings management"
},
{
"name": "Role",
"description": "custom roles management"
}
],
"security": [
{
"Token": []
},
{
"Internal": []
}
],
"include": [
"https://gitlab-dev.ispsystem.net/tools/gitlab/raw/master/conan/binary-dev-cpp20.yml"
],
"deploy_api": {
"image": "registry-dev.ispsystem.net/docker/py-ci-utility",
"stage": "deploy",
"dependencies": [
"build:alma-15"
],
"script": [
"cp build/dist/opt/ispsystem/auth/etc/schema/compat_auth.yaml ./compat_auth.yml",
"curl -s -o merge_schema.py 'https://gitlab-dev.ispsystem.net/tools/gitlab/raw/master/openapi/merge_schema.py'",
"OPENAPI_DIR=${PWD} python3 merge_schema.py > auth_v4_api.json",
"curl -T \"auth_v4_api.json\" ftp://\"common:${FTP_COMMON_PASSWORD}\"@ru.download.ispsystem.com/"
],
"only": [
"tags"
]
},
"deploy_to_confluence": {
"image": "registry-dev.ispsystem.net/docker/py-ci-utility",
"stage": "deploy",
"variables": {
"CONFLUENCE": "VM6 177964536\nV6AG 177964538\nDCImgr6 177964672\nDCI6EN 177964675\n"
},
"script": [
"python compat/auth/merge_schema.py > auth_api.json",
"cat auth_api.json | jq > /dev/null",
"curl -T \"auth_api.json\" ftp://\"common:${FTP_COMMON_PASSWORD}\"@ru.download.ispsystem.com/",
"curl -s -o deploy_to_confluence.py 'https://gitlab-dev.ispsystem.net/tools/gitlab/raw/master/openapi/deploy_to_confluence.py'",
"echo \"$CONFLUENCE\" | while read CONFLUENCE_SPACE CONFLUENCE_PID; do if [ -n \"${CONFLUENCE_SPACE}\" ]; then python deploy_to_confluence.py -sk \"${CONFLUENCE_SPACE}\" -pid \"${CONFLUENCE_PID}\" -u \"${CONFLUENCE_USER}\" -p \"${CONFLUENCE_PASSWORD}\" -f \"${CONFLUENCE_FILE}\" -du \"${CONFLUENCE_DOWNLOAD_LINK}\" -t \"${CONFLUENCE_PAGE_TITLE}\"; fi; done"
],
"only": [
"tags"
]
},
"language": "go",
"go": [
1.7
],
"script": [
"go test -v ./..."
]
}