Перейти к основному содержимому

Авторизация

API использует JWT-токены (JSON Web Token) для аутентификации запросов. Токен выдаётся по логину и паролю пользователя и передаётся в каждом последующем запросе.

Все методы API располагаются под путём /api/ относительно адреса сервера. Адрес сервера в примерах — nav.gpspos.ru; у вашей компании он может отличаться.

Получение токена​

POST /api/Token

Единственный метод API, не требующий токена.

Тело запроса:

{
  "UserName": "login",
  "Password": "password",
  "SubUserId": 0
}
  • UserName, Password — логин и пароль пользователя с доступом к API. Используется обычная учётная запись Системы: те же логин и пароль действуют в веб-интерфейсе, состав прав тот же.
  • SubUserId — идентификатор вложенной учётной записи, если у пользователя настроены субпользователи; 0, если субпользователи не используются. Токен, выданный для субпользователя, ограничивает выдачу его правами.

Ответ:

{
  "AccessToken": "eyJhbGciOiJIUzI1NiIs...",
  "UserName": "login",
  "ExpiresInSec": 1800
}
  • AccessToken — токен доступа.
  • UserName — логин пользователя, которому выдан токен.
  • ExpiresInSec — срок действия токена в секундах.

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

curl -X POST https://nav.gpspos.ru/api/Token \
  -H "Content-Type: application/json" \
  -d '{"UserName":"login","Password":"password","SubUserId":0}'

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

Токен передаётся во всех остальных запросах в заголовке Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
curl https://nav.gpspos.ru/api/Profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Токен предоставляет полный доступ к данным пользователя в рамках его прав.

Срок действия токена​

Токен действует 30 минут. Точное значение возвращается в поле ExpiresInSec и на конкретной установке может отличаться.

Метод продления токена не предусмотрен: после истечения срока токен выдаётся заново тем же запросом POST /api/Token. Запрос с истёкшим токеном возвращает 401 Unauthorized. Обращения к /Token учитываются в ограничении частоты запросов наравне с остальными методами.

Ошибки авторизации​

Ошибки возвращаются в стандартном формате:

{
  "Status": "FAIL",
  "ErrorMessage": "Invalid username or password."
}
  • 403 Forbidden при получении токена — неверный логин или пароль либо отсутствие у учётной записи доступа к API. Доступ к API включается администратором, см. Инструменты API.
  • 401 Unauthorized при вызове метода — токен отсутствует, истёк или повреждён.
  • 403 Forbidden при вызове метода — токен действителен, но у пользователя нет прав на запрошенные данные. Состав прав задаётся в панели управления.

Остальные коды состояния приведены на странице Ошибки и коды ответов.