Управление API-ключами и авторизация

В этом разделе описано, как управлять вашими ключами для взаимодействия с API Servicepipe и каковы общие принципы авторизации.

Общие принципы авторизации в API

API Servicepipe использует предсказуемые URL-адреса и стандартные функции HTTP, такие как HTTP-статус коды и аутентификация, понятные большинству HTTP-клиентов. Все ответы от API, включая ошибки, возвращаются в формате JSON.

Коды ответов

В API применяется стандартный набор HTTP-статус кодов:

  • 2xx: Запрос выполнен успешно.

  • 400 Bad Request: Ошибка в запросе из-за неверных данных (например, отсутствует обязательный параметр).

  • 401 Unauthorized: Предоставленные учетные данные недействительны или срок действия вашего токена истек.

  • 403 Forbidden: В доступе отказано, у вас недостаточно прав.

  • 404 Not Found: Запрашиваемый ресурс не существует.

  • 429 Too Many Requests: Вы превысили допустимое количество запросов.

  • 5xx Server errors: Проблема на стороне Servicepipe.

Ограничения

  • Максимальный размер тела запроса: 25 МБ.

  • Ограничения количества запросов:

    • Для аккаунта: 1000 запросов в секунду.

    • Для одного клиента: 100 запросов в секунду.

    • На эндпоинт авторизации: 10 запросов в секунду.

Типы API-токенов

Для взаимодействия с API Servicepipe используется авторизация по токену (Bearer Token). Существует два типа токенов:

  • Постоянный токен: Это ключ, который вы можете сгенерировать и которым вы управляете в панели управления. Он предназначен для регулярных, автоматизированных запросов к API от ваших скриптов или систем. Срок действия постоянного токена — 1 год.

  • Временный токен: Этот токен имеет короткий срок жизни (24 часа) и получается через отдельный API-запрос с передачей вашего логина и пароля. Он предназначен для временных сессий и используется в паре с refresh token для обновления.

Управление постоянным API-ключом

Доступ к этому разделу осуществляется через меню пользователя → Профиль → вкладка API ключ.

Создание постоянного ключа

При первом посещении вкладки API ключ постоянный ключ отсутствует.

Интерфейс до создания API ключа

Чтобы создать ваш уникальный постоянный ключ, нажмите на кнопку Сгенерировать API ключ.

Управление существующим ключом

После создания ключ отображается в соответствующем поле. Теперь вы можете управлять им с помощью набора иконок.

Интерфейс с существующим API ключом

  • Копирование: Чтобы скопировать ключ в буфер обмена, нажмите на иконку копирования (два квадрата).

  • Обновление: Для обновления (регенерации) ключа нажмите на иконку с круговой стрелкой. Система сгенерирует новый ключ, который заменит текущий.

    После обновления старый ключ немедленно перестает действовать. Все приложения и скрипты, использовавшие старый ключ, потеряют доступ к API. Не забудьте обновить ключ во всех ваших системах.

  • Удаление: Чтобы полностью удалить и аннулировать ваш ключ, нажмите на иконку с корзиной.

    Удаление ключа приведет к немедленному отзыву доступа к API для любых приложений, которые его используют. Это действие необратимо.

Важные моменты:

  • Уровень доступа, предоставляемый постоянным API-ключом, зависит от роли пользователя, который его сгенерировал.

  • При удалении пользователя из аккаунта выпущенный им API-ключ автоматически аннулируется.

  • У одного пользователя может быть только один постоянный API-ключ.

  • Более подробную информацию о методах API вы можете найти в основной документации по API.

Получение временного токена (через API)

Если вам нужен временный токен для короткой сессии, его можно получить, отправив API-запрос с вашим логином и паролем.

Метод: POST

URL:

https://api.servicepipe.ru/api/v1/auth/token

Заголовки: X-TYPE:: bd31ff6d2ff7ac330302863b553175af Content-Type:: application/json

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

{
  "username": "username",
  "password": "password"
}

Пример запроса (cURL):

curl --request POST \
--url 'https://api.servicepipe.ru/api/v1/auth/token' \
--header 'X-TYPE: bd31ff6d2ff7ac330302863b553175af' \
--header 'Content-Type: application/json' \
--data '{
"username": "username",
"password": "password"
}'

Пример успешного ответа (200 OK):

{
  "access_token": "string",
  "refreshToken": "string"
}

Полученный access_token вы можете использовать для авторизации в API, передавая его в заголовке Authorization: Bearer {access_token}.