Авторизация API 1.7.0

Методы API для работы с разделом «Авторизация».

Базовый путь: https://{IP_контроллера}/api/v1. Версия описания API: 1.7.0.

Примеры используют placeholder-значения для паролей, token, UUID, адресов и секретов. Перед выполнением запроса замените их на значения вашего контроллера.

Методы раздела

Метод	Путь
`GET`	`/auth_users`
`POST`	`/auth_users`
`GET`	`/auth_users/{login}`
`PUT`	`/auth_users/{login}`
`DELETE`	`/auth_users/{login}`
`POST`	`/extend_session`
`POST`	`/login`

`GET /auth_users`

Раздел: Авторизация.

Возвращает список всех профилей входа (Get all authorization users)

Источник в Teamly

Назначение

URL запроса

Возвращает список всех профилей входа

(Get all authorization users)

https://{IP_контроллера}/api/v1/auth_users

Варианты ответа:

Code 200 (Successfully returned all auth users) - удачное выполнение запроса

Название * - обязательный	Тип	Формат	Назначение
login*	string	minLength: 1	Имя пользователя системы
password	string	minLength: 8	Пароль для входа в систему
user*	string	pattern:/^$\|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i	UUID сотрудника привязанного к этому пользователю
role*	string	Варианты: [admin, manager, user, installer]	Роль пользователя
exp*	integer	minimum: 5	Время сессии в минутах

Пример:

Пример с исправленным синтаксисом JSON

Добавлена пропущенная запятая после user.

[
  {
    "user": "",
    "login": "admin",
    "exp": 600,
    "role": "admin"
  },
  {
    "user": "",
    "login": "manager",
    "exp": 600,
    "role": "manager"
  }
]

Исходный пример Teamly

Пример из Teamly сохранён дословно, но не является корректным JSON.

[
  {
    "user": ""
    "login": "admin",
    "exp": 600,
    "role": "admin"
  },
  {
    "user": "",
    "login": "manager",
    "exp": 600,
    "role": "manager"
  }
]

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Get all authorization users",
  "responses": {
    "200": {
      "description": "Successfully returned all auth users",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "login",
                "user",
                "role",
                "exp"
              ],
              "properties": {
                "login": {
                  "type": "string",
                  "minLength": 1
                },
                "password": {
                  "type": "string",
                  "minLength": 8
                },
                "user": {
                  "description": "UUID of user, owninig this login",
                  "type": "string"
                },
                "role": {
                  "description": "login privileges",
                  "type": "string",
                  "enum": [
                    "admin",
                    "manager",
                    "user",
                    "installer"
                  ]
                },
                "exp": {
                  "type": "integer",
                  "minimum": 5,
                  "description": "token life time"
                }
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X GET "https://{IP_контроллера}/api/v1/auth_users" \
  -H "Authorization: Bearer <token>"

Пример ответа

[
  {
    "login": "string",
    "password": "stringxx",
    "user": "string",
    "role": "admin",
    "exp": 5
  }
]

`POST /auth_users`

Раздел: Авторизация.

Добавляет нового пользователя в систему

Источник в Teamly

Use Case	URL запроса
Добавляет нового пользователя в систему	https://{IP_контроллера}/api/v1/auth_users/

Параметры запроса:

Наименование	Тип	Описание
user*	object (body)	Тело запроса
BODY
Название * - обязательный	Тип	Формат	Назначение
login*	string	Минимальная длина: 1	Имя пользователя системы
password	string	Минимальная длина: 8	Пароль для входа в систему
user*	string	pattern:/^$\|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i	UUID сотрудника привязанного к этому пользователю
role*	string	Варианты: [admin, manager, user, installer]	Роль пользователя
exp*	integer	Минимальное значение: 5 мин	Время сессии в минутах

Пример:

URL запроса: POST
https://{IP_контроллера}/api/v1/auth_users/

Body

Пример с исправленным синтаксисом JSON

Типографские кавычки заменены стандартными кавычками JSON.

{
"login": "name",
"password": "abc12345",
"user": "",
"role": "manager",
"exp": 60
}

Исходный пример Teamly

Пример из Teamly сохранён дословно, но не является корректным JSON.

{
"login": “name”,
"password": “abc12345”,
"user": “”,
"role": “manager”,
"exp": 60
}

Варианты ответа:

Code 201 (Successfully) - удачное выполнение запроса

{
  "success": true,
  "message": "string"
}

Code 400 (Bad request parameters) - запрос не выполнен, неверно указаны параметры запроса

Code 404 (User with specified login already exists) - запрос не выполнен, пользователь с таким именем уже добавлен

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Add new authorization user",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "login",
            "user",
            "role",
            "exp"
          ],
          "properties": {
            "login": {
              "type": "string",
              "minLength": 1
            },
            "password": {
              "type": "string",
              "minLength": 8
            },
            "user": {
              "description": "UUID of user, owninig this login",
              "type": "string"
            },
            "role": {
              "description": "login privileges",
              "type": "string",
              "enum": [
                "admin",
                "manager",
                "user",
                "installer"
              ]
            },
            "exp": {
              "type": "integer",
              "minimum": 5,
              "description": "token life time"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Successfully added new auth user",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid parameters",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "409": {
      "description": "User with specified login already exists",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X POST "https://{IP_контроллера}/api/v1/auth_users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "login": "string",
  "password": "stringxx",
  "user": "string",
  "role": "admin",
  "exp": 5
}'

Пример тела запроса

{
  "login": "string",
  "password": "stringxx",
  "user": "string",
  "role": "admin",
  "exp": 5
}

Пример ответа

{
  "success": false,
  "message": "string",
  "data": {}
}

`GET /auth_users/{login}`

Раздел: Авторизация.

Возвращает список настроек конкретного пользователя в соответствии с указанным значением в “login”

Источник в Teamly

Назначение	URL запроса
Возвращает список настроек конкретного пользователя в соответствии с указанным значением в “login”	https://{IP_контроллера}/api/v1/auth_users/{login}

Параметры запроса:

Наименование, * - обязательный	Описание
login* string (path)	Имя пользователя системы

Варианты ответа:

Code 200 (Successfully returned authorization user with specified login) - удачное выполнение запроса

Название, * - обязательный	Тип	Формат	Назначение
login*	string	minLength: 1	Имя пользователя системы
password	string	minLength: 8	Пароль для входа в систему
user*	string	pattern:/^$\|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i	UUID сотрудника привязанного к этому пользователю
role*	string	Варианты: [admin, manager, user, installer]	Роль пользователя
exp*	integer	minimum: 5	Время сессии в минутах

Пример:

{
  "user": "",
  "login": "admin",
  "exp": 600,
  "role": "admin"
}

Code 404 (User with specified login was not found) - запрос не выполнен, пользователь не найден

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Get authorization user",
  "parameters": [
    {
      "in": "path",
      "name": "login",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successfully returned authorization user with specified login",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "User with specified login was not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X GET "https://{IP_контроллера}/api/v1/auth_users/{login}" \
  -H "Authorization: Bearer <token>"

Пример ответа

{
  "success": false,
  "message": "string",
  "data": {}
}

`PUT /auth_users/{login}`

Раздел: Авторизация.

Позволяет отредактировать добавленного пользователя

Источник в Teamly

Назначение	URL запроса
Позволяет отредактировать добавленного пользователя	https://{IP контроллера}/api/v1/auth_users/name

Параметры запроса:

Название	Тип	Описание
login*	string (path)	Имя пользователя системы
user*	object (body)	Тело запроса
BODY
Название * - обязательный	Тип	Формат	Назначение
login*	string	minLength: 1	Имя пользователя системы
password	string	minLength: 8	Пароль для входа в систему
user*	string	pattern: /^$\|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i	Уникальный идентификатор сотрудника привязанного к этому пользователю
role*	string	Варианты admin - Администратор manager - Менеджер user - Оператор installer - Инсталлятор	Роль пользователя
exp*	integer	minimum: 5	Время сессии в минутах

Пример:

URL запроса: PUT

https://{IP контроллера}/api/v1/auth_users/name

Body

{
  "login": “name”
  "password": “abc12345”
  "user": “2e536340-8436-11ec-abed-3b4382508853”
  "role": “manager”
  "exp": 60
}

Варианты ответа:

Code 200 (Successfully) - удачное выполнение запроса пользователь успешно обновлен

Code 404 (User with specified login was not found) - запрос не выполнен, пользователь указанный вместо {login} не найден.

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Udate authorization user data",
  "parameters": [
    {
      "in": "path",
      "name": "login",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "login",
            "user",
            "role",
            "exp"
          ],
          "properties": {
            "login": {
              "type": "string",
              "minLength": 1
            },
            "password": {
              "type": "string",
              "minLength": 8
            },
            "user": {
              "description": "UUID of user, owninig this login",
              "type": "string"
            },
            "role": {
              "description": "login privileges",
              "type": "string",
              "enum": [
                "admin",
                "manager",
                "user",
                "installer"
              ]
            },
            "exp": {
              "type": "integer",
              "minimum": 5,
              "description": "token life time"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successfully updated authorization user data"
    },
    "404": {
      "description": "User with specified login was not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X PUT "https://{IP_контроллера}/api/v1/auth_users/{login}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "login": "string",
  "password": "stringxx",
  "user": "string",
  "role": "admin",
  "exp": 5
}'

Пример тела запроса

{
  "login": "string",
  "password": "stringxx",
  "user": "string",
  "role": "admin",
  "exp": 5
}

`DELETE /auth_users/{login}`

Раздел: Авторизация.

Позволяет удалить добавленного пользователя

Источник в Teamly

Назначение	URL запроса
Позволяет удалить добавленного пользователя	https://{IP_контроллера}/api/v1/auth_users/name

Параметры запроса:

Наименование, * - обязательный	Описание
login* string (path)	Имя пользователя системы

Варианты ответа:

Code 200 (Successfully delete authorization use) - удачное выполнение запроса пользователь успешно удален

Code 404 (User with specified login was not found) - запрос не выполнен, пользователь указанный вместо {login} не найден

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Delete authorization user",
  "parameters": [
    {
      "in": "path",
      "name": "login",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successfully delete authorization user"
    },
    "404": {
      "description": "User with specified login was not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X DELETE "https://{IP_контроллера}/api/v1/auth_users/{login}" \
  -H "Authorization: Bearer <token>"

`POST /extend_session`

Раздел: Авторизация.

Продлевает текущий сеанс пользователя

Источник в Teamly

Назначение	URL запроса
Продлевает текущий сеанс пользователя	https://{IP_контроллера}/api/v1/extend_session

Параметры запроса:

Параметры отсутствуют

Пример:

URL запроса: POST
https://{IP_контроллера}/api/v1/extend_session

Варианты ответа:

Code 200 (Successfully extended user session) - удачное выполнение запроса

{ 
  "user": {
    "login": "string",
    "role": "admin"
  },
  "token": "string"
}

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Extends current user session",
  "responses": {
    "200": {
      "description": "Successfully extended user session",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "user",
              "token"
            ],
            "properties": {
              "user": {
                "type": "object",
                "required": [
                  "login",
                  "role"
                ],
                "properties": {
                  "login": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "manager",
                      "user",
                      "installer"
                    ]
                  }
                }
              },
              "token": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X POST "https://{IP_контроллера}/api/v1/extend_session" \
  -H "Authorization: Bearer <token>"

Пример ответа

{
  "user": {
    "login": "string",
    "role": "admin"
  },
  "token": "string"
}

`POST /login`

Раздел: Авторизация.

Получить token авторизации (ключ доступа)

Источник в Teamly

Назначение	URL запроса
Возвращает token авторизации для работы с API методами	https://{IP_контроллера}/api/v1/login

Параметры запроса:

Параметры отсутствуют

BODY
Название * - обязательный	Тип	Формат	Назначение
login*	string	minLength: 1	имя пользователя, через которого планируется работа с api
password*	string	minLength: 8	пароль пользователя

Пример:

URL запроса: POST
https://{IP_контроллера}/api/v1/login

Body

Пример с исправленным синтаксисом JSON

Комментарии вынесены из JSON: login — имя пользователя API, password — его пароль. Учётные данные в примере демонстрационные.

{
  "login": "admin",
  "password": "abc12345"
}

Исходный пример Teamly

Пример из Teamly сохранён дословно, но не является корректным JSON.

{
  "login": "admin", /имя пользователя, через которого планируется работа с api
  "password": "abc12345" /пароль пользователя
}

Варианты ответа:

Code 201 (Successfully) - удачное выполнение запроса

{
    "user": {
        "user": "",
        "exp": 600,
        "login": "admin",
        "role": "admin"
    },

    "token": "<token>"
}

Полученный “token” нужно использовать в заголовках всех запросов к API.

По умолчанию, время жизни токена составляет 10 часов (параметр “exp": 600, в минутах).

Варианты на NodeJs использование “token” для метода GET /auth_users

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://{Ip}/api/v1/auth_users/',
  'headers': {
    'Authorization': 'Bearer <token>'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Code 401 (Bad login/password pair) - запрос не выполнен, неверная пара логин/пароль

Code 500 (Unexpected server error) - запрос не выполнен получено сообщение об ошибке

Параметры и ответы по OpenAPI

{
  "description": "Loggs in and returns auth JWT",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "login",
            "password"
          ],
          "properties": {
            "login": {
              "type": "string",
              "minLength": 1
            },
            "password": {
              "type": "string",
              "minLength": 8
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successfully logged in",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "user",
              "token"
            ],
            "properties": {
              "user": {
                "type": "object",
                "required": [
                  "login",
                  "role"
                ],
                "properties": {
                  "login": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "manager",
                      "user",
                      "installer"
                    ]
                  }
                }
              },
              "token": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Bad login/password pair",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "success"
            ],
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}

Примеры по OpenAPI

Сформированы по схеме контроллера; значения полей необходимо заменить.

Пример запроса

curl -k -X POST "https://{IP_контроллера}/api/v1/login" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "login": "string",
  "password": "stringxx"
}'

Пример тела запроса

{
  "login": "string",
  "password": "stringxx"
}

Пример ответа

{
  "user": {
    "login": "string",
    "role": "admin"
  },
  "token": "string"
}

Методы раздела​

GET /auth_users​

Примеры по OpenAPI​

Пример запроса​

Пример ответа​

POST /auth_users​

Примеры по OpenAPI​

Пример запроса​

Пример тела запроса​

Пример ответа​

GET /auth_users/{login}​

Примеры по OpenAPI​

Пример запроса​

Пример ответа​

PUT /auth_users/{login}​

Примеры по OpenAPI​

Пример запроса​

Пример тела запроса​

DELETE /auth_users/{login}​

Примеры по OpenAPI​

Пример запроса​

POST /extend_session​

Примеры по OpenAPI​

Пример запроса​

Пример ответа​

POST /login​

Примеры по OpenAPI​

Пример запроса​

Пример тела запроса​

Пример ответа​

Методы раздела

`GET /auth_users`

Примеры по OpenAPI

Пример запроса

Пример ответа

`POST /auth_users`

Примеры по OpenAPI

Пример запроса

Пример тела запроса

Пример ответа

`GET /auth_users/{login}`

Примеры по OpenAPI

Пример запроса

Пример ответа

`PUT /auth_users/{login}`

Примеры по OpenAPI

Пример запроса

Пример тела запроса

`DELETE /auth_users/{login}`

Примеры по OpenAPI

Пример запроса

`POST /extend_session`

Примеры по OpenAPI

Пример запроса

Пример ответа

`POST /login`

Примеры по OpenAPI

Пример запроса

Пример тела запроса

Пример ответа