Токен API

Токен API позволяет стороннему программному обеспечению вызывать конечные точки API Omniscol от имени школы — на чтение и, если выбраны конечные точки API на запись, на запись.

Это мощный инструмент, поэтому обращаться с ним нужно осторожно.

Создание

Токен создаётся в Общий доступ (Импорт/Экспорт > Общий доступ). Вы указываете:

• ключ (создаётся в Omniscol, с названием и возможным сроком действия; дату окончания срока можно изменить позже),
• область: список конечных точек API, которые сможет вызывать этот токен (указывайте только то, что действительно необходимо),
• при желании — срок действия токена. Эта дата записывается в созданный JWT, и изменить её потом нельзя.

Если удалить ключ или если его срок действия истёк, производные токены отзываются немедленно. Чтобы изменить срок действия отдельного токена, создайте новый JWT.

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

Токен передаётся в HTTP-заголовке Authorization: Bearer <token> или (для рабочей среды это менее рекомендуется) в URL через ?auth=<token>.

Рекомендации

• Один ключ на интеграцию — так проще отзывать их независимо.
• Минимальный набор прав — отмечайте только нужные API, а не всё по умолчанию.
• Срок действия на нужном уровне — срок действия ключа подходит для управления интеграцией в долгосрочной перспективе; срок действия токена — для временного доступа, который нельзя изменить.
• Регулярная ротация — создавайте ключ заново каждые 6–12 месяцев.
• Не храните в Git — токен не должен оказаться под версионным контролем в публичном репозитории. Используйте переменные окружения вашего сервера.

Отличие от OIDC / SSO

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