API и ключи доступа

У платформы есть собственный API: то же самое, чем пользуется приложение. Обычный вход в него — сессия пользователя, а для скрипта, интеграции или дашборда, которые работают сами по себе, выдаётся ключ доступа.

Как получить ключ

Ключ получают на странице «Для разработчиков» (адрес /developers): на компьютере — пункт бокового меню в разделе «Заявки», на телефоне — тот же пункт в меню «☰» или «Настройки» → «Для разработчиков» → «API-ключ и документация». Страница видна после входа. Там же ссылка «Документация API» (открывается в новой вкладке). Ключ не связан с ролью преподавателя или сотрудника: роль запрашивается на странице «Моя роль», а ключа там нет.

Путей два. Если у вашей роли есть право «Выпуск API-ключа себе без заявки» (или «Выпуск и отзыв API-ключей»), ключ выпускается сразу, без заявки — см. «Выпустить ключ себе». У остальных — заявка, которую рассматривает человек с правом «Выпуск и отзыв API-ключей».

Выпустить ключ себе

Тем, кому это можно, на странице вместо заявки показана форма с кнопкой «Выпустить ключ». Никто её не рассматривает, поэтому всё, что обычно решает рассматривающий, вы решаете сами:

• Кому или для чего — необязательно; как ключ подписан в списке. Если оставить пустым, подписью станет начало цели.
• Что разрешено ключу — отметки из прав вашей роли, и только из них; «Выбрать все» и «Снять все» отмечают всё сразу. Отмечайте только то, что нужно скрипту. Без отметок ключ читает только то, что доступно любому посетителю, но со своим лимитом запросов.
• Действует до — обязательно. По умолчанию через год, не дольше 730 дней. Когда срок выйдет, ключ перестанет работать — выпустите новый.
• Цель — обязательно: что и как часто будет вызываться. Она сохраняется на учётной записи, как причина выдачи.

У «Что разрешено ключу», «Действует до» и у кнопки есть подсказки: на компьютере — при наведении, на телефоне — долгим нажатием.

После «Выпустить ключ» прежний ключ, если он был, сразу перестаёт работать, а новый появляется на карточке целиком — скопируйте его кнопкой «Скопировать». Выпуск записывается в журнал аудита так же, как одобренная заявка («API-ключ выпущен»), с пометкой, что ключ выпустил сам владелец. Выпускать ключ себе можно не чаще пяти раз в час. Пока ключ действует, вместо формы на странице — сам ключ и «Перевыпустить».

Заявка на ключ

В заявке два обязательных поля:

• Кому или для чего — что будет ходить по ключу: «экспорт расписания в деканате», «бот кафедры», «дашборд в Grafana». Эта строка потом видна в списке выданных ключей.
• Цель — что именно и как часто будет вызываться. Хватит и одного слова, но по этому тексту заявку и рассматривают: если из него не понять, зачем ключ, заявку отклонят с комментарием.

Кнопка «Запросить ключ» отправляет заявку. Заявку видят все, кто имеет право «Выпуск и отзыв API-ключей». Решение приходит уведомлением — в колокольчик, в push и в бот, если он подключён. Одна заявка на рассмотрении за раз.

Что решает рассматривающий

Заявка одобряется не «да» или «нет», а с настройками:

• Что разрешено ключу — набор прав. Ключ не может больше, чем его владелец: всё, чего нет у роли заявителя, отбрасывается.
• Действует до — дата, после которой ключ перестаёт работать. Можно оставить пустым — тогда ключ бессрочный.
• Название — как ключ подписан в списке; по умолчанию это строка «Кому или для чего».
• Комментарий — то, что прочитает заявитель.

Причина выдачи сохраняется на учётной записи: в списке пользователей рядом с именем появляется значок ключа, а на странице пользователя — строка «Зачем выдан».

Как пользоваться ключом

Ключ показывается его владельцу целиком — на той же странице «Для разработчиков», где он получен: «Показать ключ», «Скопировать». Он начинается с vish_; в списках ключ виден только первыми символами.

Ключ передаётся в заголовке X-Api-Key:

curl -H "X-Api-Key: vish_..." https://api.<стенд>/api/v1/schedule/lessons

Заголовок отдельный от Authorization, чтобы ключ и сессию нельзя было перепутать. Запрос по ключу — это запрос от имени владельца, но только в пределах выданных прав: чего нет в наборе, тому ключ получит отказ, даже если у самого человека это право есть.

Описание всех методов — на странице OpenAPI, ссылка на неё есть в меню «Документация API». С чего начать, как войти, как читать расписание и справочники, с примерами на JavaScript, Python и Go, — в разделе руководства «Для разработчиков», начиная со страницы Разработчикам: начало работы; список этих страниц есть и на странице «Для разработчиков».

Перевыпуск и отзыв

Перевыпустить ключ может сам владелец, кнопкой «Перевыпустить» на странице «Для разработчиков». Старая строка перестаёт работать в тот же момент — это то, что нужно сделать, если ключ где-то засветился. Права и срок остаются прежними.

Отозвать ключ может тот, кто имеет право «Выпуск и отзыв API-ключей», на странице «Заявки», вкладка «Выданные ключи». Отзыв требует причины: она приходит владельцу уведомлением и остаётся в пометке на его учётной записи. Отозванный ключ не восстанавливается — нужна новая заявка (или новый выпуск, если вы можете выпускать ключ себе).

Выдача, перевыпуск и отзыв записываются в журнал аудита.

Войти через ВИШ

Пока ключ действует, на той же странице «Для разработчиков» можно зарегистрировать свой сайт или приложение для входа аккаунтом ВИШ: раздел «Войти через ВИШ — ваши приложения». Люди входят в него через Telegram или MAX, а приложение получает только то, что они разрешили. Как это устроено для читателей, разработчиков и администраторов — на странице Вход через ВИШ.

Проверено: 2026-10, PWA fbb681a8, platform 3474bfa8.