=  Команда login  =

== Назначение команды ==

Выполнение большинства команд API требует аутентификации - наличия в запросе клиента данных, доказывающих, что пользователь, от имени которого запрашивается выполнение команды, действительно является тем, за кого он себя выдает. Таким доказательством является наличие в запросе cookies, переданных сервером в ответе на ранее выполненный запрос.

Но как быть, если клиент собирается сделать запрос первый раз, и никаких cookies у него еще нет? Для такого случая существует команда `login`. Она выполняется даже в том случае, если в запросе клиента отсутствуют cookies. Команде `login` передается имя пользователя и пароль. Сервер проверяет, действительно ли в его базе данных есть запись о пользователе с указанным именем, и если да, сервер генерирует cookies с данными аутентификации, которые клиент затем может использовать при отправке последующих запросов.

== Ключи запроса ==

||  '''Ключ'''  ||  '''Тип значения'''  ||  '''обязательный'''  ||  '''Описание'''  ||
||  cmd  ||  строка  ||  да  || "login" - имя команды ||
||  login  ||  строка  ||  да  || имя пользователя, запрашивающего аутентификацию ||
||  password  ||  строка  ||  да  || пароль пользователя ||

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

 `{"cmd":"login","login":"john","password":"kajd64#M-ls84"}`

== Права доступа ==

Для выполнения команды `login` не требуется наличия каких-либо прав.

== Возвращаемые данные ==

В случае успешного выполнения команда `login` генерирует данные аутентификации и устанавливает cookies. В JSON-объекте ответа никакие дополнительные данные не передаются. Пример ответа в случае успешной аутентификации пользователя:

 `{"cmd":"login"}`

В случае ошибки аутентификации (пользователя с указанным именем не существует или указан неверный пароль) команда `login` возвращает ключ `error2`, значением которого является строка "неверное имя или пароль":

 `{"cmd":"login","error2":"неверное имя или пароль"}`

== Совместимость ==

В версиях аппаратуры MC04-DSL-3U до июня 2013 г. (до ревизии sw r860), где использовался внешний сервер HTTP, при передаче команды `login` для аутентификации в URI запроса вместо `api.php` требовалось использовать `login.php`. В современных версиях аппаратуры (начиная с r860) пути `/api.php` и `/login.php` равнозначны.

== См. также ==

[wiki:ApiAdduser команда adduser]