Аутентификация

Каждый пользователь в системе Idealist имеет уникальный идентификатор в формате ObjectId. Пользователи, которые могут быть авторизованы через пользовательский интерфейс, имеют параметр username, который так же уникален.

Для аутентификации пользователя в запросе необходим сессионный ключ. Этот ключ является строкой, значение которой - валидный UUID. За исключением постоянных сессий (о них ниже), ключ действителен в течение 48 часов с момента последнего запроса.

Использование

Ключ может быть передан двумя способами:

  1. В cookie с названием session

  2. В заголовке Authorization с типом Bearer

Использование cookie обусловлено необходимостью поддержки браузеров. Если вы не работаете с API из браузера, проще и понятнее использовать заголовок Authorization

Запрос с использованием Cookie

curl --header "Cookie: session=d6f0cb68-a176-464a-82dc-a2958b99c1fb" http://demo.idealist.one/api/session -vvv

> GET /api/session HTTP/1.1
> Host: demo.idealist.one
> User-Agent: curl/7.56.1
> Accept: */*
> Cookie: session=d6f0cb68-a176-464a-82dc-a2958b99c1fb

Запрос с использованием Authorization

curl --header "Authorization: Bearer d6f0cb68-a176-464a-82dc-a2958b99c1fb" http://demo.idealist.one/api/session -vvv

> GET /api/session HTTP/1.1
> Host: demo.idealist.one
> User-Agent: curl/7.56.1
> Accept: */*
> Authorization: Bearer d6f0cb68-a176-464a-82dc-a2958b99c1fb

Пользователи с ролью apiclient могут использовать постоянный сессионный ключ, не ограниченный по времени работы. Использование такого ключа возможно только с заголовком Authorization и требует добавление префикса persistent с пробелом

Запрос с использованием постоянного ключа

curl --header "Authorization: Bearer persistent d6f0cb68-a176-464a-82dc-a2958b99c1fb" http://demo.idealist.one/api/session -vvv

> GET /api/session HTTP/1.1
> Host: demo.idealist.one
> User-Agent: curl/7.56.1
> Accept: */*
> Authorization: Bearer persistent d6f0cb68-a176-464a-82dc-a2958b99c1fb

Получение сессии

Постоянный ключ для пользователей apiclient может быть получен только через интерфейс администратора. При необходимости его смена может быть выполнена там же.

Все остальные пользователи могут выполнить авторизацию, используя API POST /api/session. Для этого необходимо передать JSON-объект с ключами username и password:

{
  "username": "admin"
  "password": "password"
}

Запрос авторизации

curl -X POST http://demo.idealist.one/api/session -d '{"username":"admin","password":"password"}' -vvv

> POST /api/session HTTP/1.1
> Host: demo.idealist.one
> User-Agent: curl/7.56.1
> Accept: */*
> Content-Length: 42

< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Tue, 28 Nov 2017 08:25:31 GMT
< Server: nginx/1.10.2
< Set-Cookie: session=98ad49ac-f192-410f-be88-ba6ed4ef7743; Expires=Thu, 30-Nov-2017 08:25:31 GMT; HttpOnly; Path=/
< X-Expires-In: 1512030331
< Content-Length: 961
< Connection: keep-alive

{
  "authorization":"98ad49ac-f192-410f-be88-ba6ed4ef7743",
  "user": {
    "_cls":"User.Worker",
    "id":"55c1ceb28ea6c67beadcdb6c",
    "active":true,
    "username":"admin",
    "name":"Анисим Матвеев (Директор)",
    "first_name":"Анисим",
    "last_name":"Матвеев",
    "role":"admin",
    "job_title":"Директор",
    "image":null,
    "units":[]
  },
  "franchising_enabled": false
}

В ответе на запрос придет JSON с информацией о пользователе и параметрах аутентификации. Сервер автоматически установит заголовок Set-Cookie и продублирует токен в параметре authorization ответа. Если вы используете авторизацию через заголовок Authorization, cookie можно проигнорировать. Соответственно, cookie можно использовать для сессий requests или аналогичных инструментов в других библиотеках.