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

Большинство запросов к API требуют аутентификации с помощью API ключа. Без ключа доступны только публичные эндпоинты: например, отправка сигнала пульсара (/v1/heartbeats/{id}/ping), подписка на Статус Страницу и данные публичных Статус Страниц.

Передача ключа

Ключ можно передать в одном из двух заголовков.

В заголовке Authorization без префикса:

curl https://api.pingera.ru/v1/checks \
  -H "Authorization: ВАШ_API_КЛЮЧ"

В заголовке X-API-KEY:

curl https://api.pingera.ru/v1/checks \
  -H "X-API-KEY: ВАШ_API_КЛЮЧ"

warning

Не добавляйте префикс Bearer к API ключу. Запрос с заголовком Authorization: Bearer ВАШ_API_КЛЮЧ будет отклонён с ошибкой 401. Префикс Bearer используется только для сессионных токенов веб-интерфейса, которые живут 12 часов и не предназначены для интеграций.

Свойства API ключа

Ключ — строка из 64 шестнадцатеричных символов.
Срок действия не ограничен: ключ работает, пока вы его не удалите.
Ключ привязан к пользователю, который его создал, и действует с правами этого пользователя (см. Роли).
При удалении пользователя из организации все его ключи удаляются.
Платформа запоминает время последнего использования ключа (last_used_at), чтобы вы могли найти неиспользуемые ключи.

Управление ключами

Создавать и удалять ключи можно в разделе Настройки → API ключи или через API.

Создать ключ

POST /v1/api-tokens

curl -X POST https://api.pingera.ru/v1/api-tokens \
  -H "Authorization: ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD pipeline"}'

Поле	Тип	Описание
`name`	`string`	Название ключа, до 100 символов. Обязательное.

Ответ 201 Created:

{
  "id": "k3x9q2m7a1bz",
  "name": "CI/CD pipeline",
  "token": "3f1c0e5a9b8d7c6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e",
  "created_at": "2026-10-08T10:00:00",
  "last_used_at": null
}

к сведению

Значение token возвращается только один раз — в ответе на создание. Сохраните его сразу в надёжном месте.

Список ключей

GET /v1/api-tokens

Возвращает массив ключей текущего пользователя. Поле token в списке всегда null.

Удалить ключ

DELETE /v1/api-tokens/{token_id}

Ключ перестаёт работать сразу после удаления. Ответ — 204 No Content.

Роли

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

Роль	Доступ через API
`viewer`	Чтение данных: проверки, результаты, Статус Страницы, инциденты, оповещения. Значения секретов не возвращаются.
`billing`	Чтение, как у `viewer`, а также подписка, способы оплаты, реквизиты для счетов и журнал аудита.
`editor`	Чтение, создание, изменение и удаление ресурсов: проверок, пульсаров, Статус Страниц, инцидентов, оповещений, секретов.
`admin`	Всё, что доступно `editor` и `billing`, а также настройки организации и управление пользователями.

Подробная таблица прав — в разделе Организация и пользователи.

Ошибки аутентификации

HTTP	`code`	Причина
401	`invalid_token`	Ключ не передан, неверен или был удалён.
401	`token_expired`	Истёк сессионный токен (`Bearer`). К API ключам не относится.
403	`insufficient_permissions`	Роли пользователя недостаточно для операции.

{
  "code": "insufficient_permissions",
  "message": "Access denied. Required role: editor or higher"
}

Полный список ошибок — в разделе Ошибки.

Передача ключа​

Свойства API ключа​

Управление ключами​

Создать ключ​

Список ключей​

Удалить ключ​

Роли​

Ошибки аутентификации​

Рекомендации по безопасности​