Права доступа (RBAC)

Доступ в ВИШ строится на ролях (RBAC): у каждого аккаунта одна роль, у роли — набор прав, а методы API требуют определённых прав. Ключ API и токен OAuth права только сужают и никогда не расширяют. Сверено со стендом d1 23 октября 2026 года.

Роли

Роль определяет, что человек может в приложении. Встроенные роли:

Администраторы могут завести и свои роли. Роль аккаунта и его права — в ответе GET /auth/me (поля role и permissions).

Права

Право — строка вида область:объект:действие. Несколько, которые чаще всего нужны интеграциям:

Полный список с описаниями отдаёт GET /rbac/permissions — для него нужно право rbac:roles:read. Какие права требует конкретный метод, сказано в его описании в OpenAPI (/documentation).

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

Как проверяется запрос

1. Кто вы. Ключ из X-Api-Key, иначе токен из Authorization: Bearer. Нет ни того ни другого — открытые методы отвечают как всем, остальные — 401 AUTH_REQUIRED.
2. Права роли. Читаются заново при каждом запросе: если роль сменили, это действует сразу, а не когда истечёт токен.
3. Сужение. У ключа права — пересечение того, что отметили при выпуске, и того, что роль даёт сейчас. У токена OAuth прав роли нет вовсе: только чтение из короткого списка методов, которые называет его scope.
4. Режим просмотра. Аккаунт в режиме просмотра (роль «Инспектор») может только читать: любой изменяющий запрос — 403 VIEW_ONLY, с ключом тоже.
5. Проверка метода. Нет нужного права — 403 FORBIDDEN, в error.message названы недостающие права.

Что значит 403

Опирайтесь на error.code: текст сообщения переводится и может меняться.

Как получить больше прав

• Роль. В приложении — «Моя роль» (/role, или «Настройки» → «Доступ»): заявка на роль преподавателя или сотрудника. Её рассматривает сотрудник института; решение приходит уведомлением.
• Ключ. Ключ не может больше, чем ваша роль. Если роль получила новые права, а ключ — нет, перевыпуск их не добавит (права и срок остаются прежними): нужен новый ключ — через заявку или выпуском себе, см. API и ключи доступа.
• Приложение «Входа через ВИШ». Запрашивайте только те scope, что нужны; список разрешённых задаётся при регистрации.

Какие методы открыты

Открытый метод — тот, у которого в OpenAPI нет требования security. Пример считает такие методы по документу самого стенда:

// Count public and protected operations in the stand's own OpenAPI document.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'
const DOC = new URL('/documentation/json', API)

const response = await fetch(DOC)
if (!response.ok) throw new Error(`${DOC}: HTTP ${response.status}`)
const openapi = await response.json()

const operations = Object.entries(openapi.paths).flatMap(([path, methods]) =>
	Object.entries(methods).map(([method, operation]) => ({
		line: `${method.toUpperCase()} ${path}`,
		isPublic: !operation.security?.length,
	})),
)
const isPublic = (line) => operations.find((operation) => operation.line === line)?.isPublic

if (isPublic('GET /api/v1/groups') !== true || isPublic('GET /api/v1/auth/me') !== false) {
	throw new Error('unexpected security in the OpenAPI document')
}
const open = operations.filter((operation) => operation.isPublic && operation.line.startsWith('GET '))
console.log(`${operations.length} operations, ${open.length} public GETs, for example:`)
for (const operation of open.slice(0, 8)) console.log(' ', operation.line)

Свои роль и права можно посмотреть так (с ключом в поле «Ключ API»):

Проверено: 2026-10, PWA aa337c45, platform bff65fce.