REST API VideoGrace Server

REST API используется для интеграции VideoGrace Server с внешними системами: порталами, CRM, helpdesk, внутренними личными кабинетами и средствами автоматизации. Через API можно создавать и обновлять пользователей, управлять группами, конференциями, правами доступа, получать данные dashboard/monitoring и встраивать VideoGrace в существующие бизнес-процессы.

API не заменяет панель администратора, а дополняет ее там, где нужны массовые операции или синхронизация с внешним источником данных.

Базовый адрес

Запросы выполняются к серверу VideoGrace по тому же домену и TCP-порту, которые используются клиентами:

https://<адрес_сервера>/

Для публичного сервера рекомендуется использовать домен и доверенный TLS-сертификат. См. инструкцию развертывания на VPS со своим доменом и Let's Encrypt.

Типовые сценарии

REST API обычно применяют для следующих задач:

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

Безопасность

API должен быть доступен только доверенным системам. Для production-инсталляции рекомендуется:

использовать только HTTPS;
ограничить доступ к API на уровне firewall или reverse proxy, если API нужен только внутренним сервисам;
использовать Authorization: Bearer <access_token>;
для сервисов использовать отдельную service account с минимально необходимыми правами;
не использовать учетную запись владельца платформы в автоматических скриптах;
хранить пароли и токены интеграций вне исходного кода.

Административные методы API должны вызываться только пользователем или токеном с соответствующими правами. Наличие обычного пользовательского логина не дает доступа к управлению сервером.

Если на сервере задан [Auth] JwtSecret или VG_JWT_SECRET, bearer token является JWT HS256. Сервер проверяет подпись, срок действия, aud=videograce, typ=access, права пользователя и отзыв по jti. Если JWT-secret не задан, возможен legacy opaque token, но для production рекомендуется включить JWT.

Обновление токена

После входа клиент может получить refresh_token. Для выпуска нового access token используйте:

POST /api/v1.0?auth_refresh
Content-Type: application/json

{
  "refresh_token": "..."
}

Ответ:

{
  "result": 200,
  "access_token": "...",
  "token_type": "Bearer"
}

refresh_token не подходит для вызова API напрямую. В REST-запросах используется только access_token:

GET /api/v1.0?server_info
Authorization: Bearer <access_token>

Данные и идентификаторы

При интеграции важно различать:

Сущность	Назначение
Пользователь	Учетная запись человека или сервисного клиента
Группа	Организационная структура и видимость контактов
Конференция	Постоянная или временная комната для аудио/видео/чата
Тег конференции	Человекочитаемый идентификатор конференции и часть URL
Grants	Битовая маска прав пользователя

Для массовой загрузки пользователей сначала определите структуру групп, затем создавайте пользователей и привязывайте их к нужным группам.