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

Токены доступа

Для использования HTTP API платформы необходим API токен доступа, который указывается в каждом запросе в заголовке Authorization после слова Bearer в формате:

Authorization: Bearer <ACCESS_TOKEN>

Издать токен можно вручную в разделе администрирования проекта (opens in a new tab)

• Подробнее об издании API токена в разделе администрирования

Помимо ручного создания токенов доступа существует возможность использовать cпециальный метод API

Издание токена - аутентификация

В теле запроса необходимо передать учётные данные, которые были использованы при регистрации.

{
  "username": "test@example.com",
  "password": "***********"
}

В успешном ответе будет содержаться несколько служебных полей, таких как информация о пользователе, срок действия токена и т.д.

{
  "_id": "66a66b2207dfcec6494cd618",
  "issuedAt": 1722182434022,
  "expiresAt": 1729958434022,
  "user": {
    "name": "test@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

При издании токена можно задать дополнительные параметры expiresIn и scopes:

{
  "username": "test@example.com",
  "password": "***********",
  "expiresIn": "90 days",
  "scopes": [
    "GET /objects",
    "GET /objects/:id",
    "POST /objects/:id/commands/:command",
    "GET /geofences",
    "POST /geofences",
    "DELETE /geofences/:id"
  ]
}

expiresIn - срок действия

Если не указывать данный параметр, срок действия токена будет огрничен значением по умолчанию - 1 день.
Значения параметра можно передавать в следующем виде:

• 30 minutes
• 12 hours
• 8 days
• 5 years

scopes - разрешенные дейтсвия

Позволяет задать список методов, к которым будет иметь доступ токен.
Название метода формируется как "<МЕТОД> <API-путь>", при этом префикс /api/v1 указывать не обязательно. Например:

• GET /objects - получение списка объектов
• POST /objects - создание объекта
• PATCH /objects/:id - изменение объекта

Полный список доступных методов можно получить через API:

• GET /users/scopes (opens in a new tab)

Методы управления токенами

Получить список

Позволяет получить список всех изданных токенов доступа в рамках проекта.

[
  {
    "_id": "66a64c586a8ed41e84ece92b",
    "name": "get-objects-01",
    "expiresAt": 1724706000000,
    "scopes": ["GET /objects", "GET /objects/:id/packets"]
  },
  {
    "_id": "66a64c586a8ed41e84ece92b",
    "name": "post-objects-01",
    "expiresAt": 1724706000000,
    "scopes": ["POST /objects"]
  }
]

Издание токена

Помимо издания токена путём указания учётных данных (username и password) существует возможность издать новый токен с помощью метода POST /tokens и ранее изданного токена:

{
  "expiresIn": "7 days",
  "name": "test-token-01",
  "scopes": ["POST /tokens", "GET /objects"]
}

Параметр name является необязательным, но может упростить администрирование токенов.

Отозвать токен

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