API Omniscol — токены аутентификации

Ключ и токен: два разных объекта

Omniscol различает два объекта, которые нельзя путать.

Ключ — постоянный объект, который хранится на стороне Omniscol. Он включает:

• короткий идентификатор, сгенерированный случайным образом и открытый: именно его показывает список, и он входит в каждый токен, чтобы указать, какой ключ нужно проверять;
• описательное название, которое можно изменить в любой момент;
• необязательную дату окончания срока действия, которую можно изменить в любой момент;
• длинный случайный секрет, созданный на стороне сервера и служащий криптографическим ключом подписи.

Идентификатор, название и дата окончания срока действия — это административные сведения: идентификатор является лишь открытой ссылкой, а не секретом. Секрет же — единственный материал для подписи: он генерируется случайным образом при создании ключа, остаётся на стороне сервера, не изменяется и никогда не отображается и не передаётся — ни при создании, ни в списке ключей. Даже если бы он утёк, этого не хватило бы для подделки токена: подпись сочетает его с солью, уникальной для аккаунта, и с серверным секретом, которые тоже никогда не покидают Omniscol.

Токен — это автономный JWT (JSON Web Token), подписанный секретом ключа. Именно его вы передаёте внешней системе. Его подписанное содержимое включает соответствующий аккаунт, список разрешённых конечных точек, ключ, на основе которого он создан, и собственную дату окончания срока действия.

Иначе говоря: ключ подписывает, токен подписан. Один ключ может подписать несколько токенов — все они проверяются одним и тем же секретом, поэтому все они отзываются вместе, если ключ исчезнет.

Omniscol не хранит токен: он генерирует его, показывает один раз, а затем проверяет заново при каждом вызове, восстанавливая подпись по секрету ключа (HMAC SHA-256). Поэтому разрешения, заложенные в токен, невозможно изменить без этого секрета.

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

Экран «Общий доступ» доступен в разделе Администрирование → Импорт/Экспорт на аккаунтах Premium. Создание проходит в два этапа: сначала создаётся ключ, затем по этому ключу генерируется токен.

1. Создать ключ — укажите понятное название и, если доступ временный, дату окончания срока действия. Название и срок действия можно изменить позже; секрет подписи изменить нельзя.
2. Сгенерировать токен — выберите ключ, отметьте разрешённые конечные точки, при желании задайте дату окончания срока действия самого токена и сгенерируйте JWT.

При генерации Omniscol показывает токен только один раз. Сразу скопируйте его в менеджер секретов: повторно он не отобразится. Срок действия токена записан в его подписанном содержимом, поэтому позже его изменить нельзя. Чтобы изменить эту дату, сгенерируйте новый токен.

Таким образом, существует два независимых друг от друга уровня срока действия:

• срок действия ключа — изменяется в списке ключей; по его истечении все токены, созданные на основе этого ключа, отклоняются (вызов завершается ошибкой 401);
• срок действия токена — задаётся при генерации, записывается в JWT и затем не изменяется.

Разрешённые конечные точки

Токен даёт доступ только к конечным точкам, отмеченным при его генерации: никогда не считайте, что он охватывает весь API. Список разрешённых точек передаётся внутри токена и проверяется при каждом вызове; обращение к неразрешённой конечной точке отклоняется (401).

Помимо отдельных конечных точек, в списке выбора есть быстрый выбор по модулям:

• пункт самого модуля, без уточнения операции, разрешает все его конечные точки;
• варианты по операциям — чтение, изменение, создание, удаление — ограничивают модуль одним типом вызовов.

Так, пункт «Расписание [чтение]» открывает весь доступ на чтение расписаний, не давая никакой возможности записи, и избавляет от необходимости отмечать каждую конечную точку по отдельности. Выдавайте минимум: только те модули и операции, которые строго необходимы для интеграции.

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

Токен отправляется в API двумя обычными способами:

• HTTP-заголовок: Authorization: Bearer <токен> (рекомендуется).
• Строка запроса: ?auth=<токен> (удобно для отладки, но попадает в HTTP-журналы — в рабочей среде лучше избегать).

Пример curl, который нужно адаптировать под реальную конечную точку из OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://vasha-shkola.omniscol.com/api/<модуль>/<конечная-точка>

Документация OpenAPI

На экране «Импорт/Экспорт» есть ссылка OpenAPI 3.1, которая открывает в Swagger Editor спецификацию, доступную для аккаунта. В ней вы найдёте:

• список предоставляемых конечных точек API,
• схемы обмениваемых данных,
• методы и параметры,
• ожидаемые ответы.

Спецификацию также напрямую отдаёт ваш аккаунт, без аутентификации:

• /api/guest/openapi.json — спецификация в формате JSON;
• /api/guest/openapi.yaml (или /api/guest/openapi?yaml=true) — то же содержимое в формате YAML;
• /api/guest/school_schema.json — JSON-схема данных аккаунта.

Полная справка для вашего ИИ-ассистента

Портал также публикует всю справку Omniscol одним текстовым файлом, который можно использовать как базу знаний для ИИ-ассистента (проект Claude, пользовательский GPT и т. п.):

• omniscol.com/ru/llms-full.txt — полное руководство в формате Markdown, доступное на каждом языке справки (/en/llms-full.txt, /fr/llms-full.txt…);
• omniscol.com/llms.txt — индекс по стандарту llms.txt, который ИИ-системы находят автоматически.

Отзыв доступа

Отзыв выполняется на уровне ключа, а не отдельного токена.

На экране перечислены ключи, по которым были сгенерированы токены. Удаление ключа стирает его секрет подписи на стороне Omniscol: после этого ни одну подпись, полученную от этого секрета, проверить уже нельзя, и любой вызов с токеном, созданным на основе этого ключа, завершается ошибкой 401. Токены делает недействительными отсутствие секрета, а не список отозванных токенов.

Для ИТ-отдела из этого следуют два вывода:

• Отзыва по отдельным токенам нет. Omniscol не хранит выданные JWT и не может отключить один из них по отдельности: уже сгенерированный токен остаётся действительным до окончания собственного срока действия или до тех пор, пока его ключ не будет удалён или не истечёт.
• Изменение срока действия ключа сразу влияет на все его токены: если перенести эту дату на более ранний срок, доступ закрывается у всех токенов, созданных на основе ключа.

Рекомендация: немедленно удалите любой ключ, в утечке которого вы подозреваете, затем создайте взамен новый ключ с понятным названием.

Один ключ на каждую систему и каждое назначение

Поскольку отзыв выполняется по ключу, заведите отдельный ключ для каждой интеграции (одна внешняя программа — один ключ). Секрет ключа подписывает только его собственные токены: удаление такого ключа лишает доступа только соответствующую интеграцию, не затрагивая остальные.

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

Для каких интеграций

API обычно применяется для:

• собственных систем информационных табло (помимо встроенных информационных панелей Omniscol; см. Настройка панелей),
• внешних сводных панелей, объединяющих Omniscol и другие источники,
• коннекторов и синхронизации с ERP или прикладной информационной системой,
• ИИ-агентов с поддержкой MCP, работающих с Omniscol через сервер MCP; см. MCP — подключение ИИ-агента.

Для доступа, делегированного идентифицированному стороннему сервису (токен с ограниченной областью действия, согласие пользователя, отзыв отключением клиента) лучше использовать сервер OAuth2 Omniscol: см. OAuth2 / OIDC (поставщик).