Публичный API webfas

webfas — облачный WAF: reverse-proxy защита сайтов и API для российского рынка. Всё, что доступно в личном кабинете, доступно и через HTTP API — управление доменами, журналом событий безопасности, правилами, Anti-Bot, сертификатами и биллингом.

API находится в разработке. Эта страница описывает целевой контракт, по которому пишется бэкенд. До публичного запуска состав полей и эндпоинтов может уточняться без обратной совместимости. Не закладывайтесь на контракт в production-интеграциях — следите за обновлениями на этой странице.

Обзор

Базовый URL

https://api.webfas.ru/v1

Аутентификация

Authorization: Bearer <jwt>

Формат данных

JSON (application/json), кодировка UTF-8

Формат ошибок

{ "error": { "code": "…", "message": "…" } }

Пагинация списков

запрос ?page=&per=&sort=&filters… → ответ { items, total, page, per }

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

ULID — сортируемые по времени, 26 символов

Время

ISO 8601, всегда UTC — например 2026-08-22T14:30:00Z

Пример запроса и ошибочного ответа:

GET /v1/domains?page=1&per=20 HTTP/1.1
Host: api.webfas.ru
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "error": { "code": "unauthorized", "message": "Токен просрочен или отозван" } }

Токен выдаётся после POST /auth/login (и POST /auth/2fa, если включена двухфакторная аутентификация) либо создаётся как долгоживущий API-токен в разделе «Интеграции» кабинета.

Сущности

Поля и типы соответствуют zod-схемам фронтенда (src/entities/index.ts) — это единый источник истины для кабинета и бэкенда. Типы указаны в TS-нотации; ulid — строковый ULID, ISO 8601 — строка даты-времени в UTC.

Account аккаунт компании

Поле	Тип	Описание
id	ulid	Идентификатор аккаунта
name	string	Название компании
plan	'start' \| 'business' \| 'enterprise'	Тарифный план
createdAt	ISO 8601	Дата регистрации

User пользователь кабинета

Поле	Тип	Описание
id	ulid	Идентификатор пользователя
email	string	E-mail (логин)
name	string	Имя и фамилия
role	'owner' \| 'admin' \| 'analyst' \| 'viewer'	Роль в команде
twoFa	boolean	Включена ли двухфакторная аутентификация
lastLoginAt	ISO 8601 \| null	Последний вход; `null` — ещё не входил

Domain защищаемый домен

Поле	Тип	Описание
id	ulid	Идентификатор домена
host	string	Имя хоста, например `example.com`
mode	'monitor' \| 'partial' \| 'block'	Режим WAF: наблюдение / частичная / полная блокировка
protected	boolean	Проксируется ли трафик через webfas
originIp	string	IP исходного сервера (в кабинете скрыт точками)
reqPerDay	number	Запросов за сутки
blockedPerDay	number	Блокировок за сутки
p50Ms	number	Медианная задержка обработки, мс
cert	{ issuer, validTo, auto }	Сводка сертификата: издатель, срок действия, автопродление
createdAt	ISO 8601	Дата добавления домена
monitorDaysoptional	number	Дней в режиме мониторинга — для подсказки «пора включать блокировку»

SecurityEvent событие безопасности

Поле	Тип	Описание
id	ulid	Идентификатор события
ts	ISO 8601	Момент запроса
domainId	ulid	Домен, на который пришёл запрос
verdict	'blocked' \| 'challenged' \| 'passed'	Вердикт WAF
attackType	string	Тип атаки: SQLi, XSS, path traversal и т. д.
method	string	HTTP-метод запроса
path	string	Путь запроса
payloadExcerpt	string	Вредоносный фрагмент запроса. Заведомо враждебная строка — выводить только как текст, без интерпретации HTML
ip	string	IP источника
country	string	Страна источника (ISO-код)
asn	string	Автономная система источника
ja4	string	JA4-отпечаток TLS-клиента
ruleId	string \| null	Сработавшее правило; `null` — вердикт вынесен движком
confidence	number \| null	Уверенность движка, 0…1
processingMs	number	Время обработки запроса, мс
userAgent	string	User-Agent клиента

Rule правило WAF

Поле	Тип	Описание
id	ulid	Идентификатор правила
name	string	Название
scope	ulid \| null	Домен действия; `null` — все домены аккаунта
kind	'custom' \| 'exception' \| 'vpatch'	Вид: пользовательское / исключение / виртуальный патч
expr	string	Выражение правила (текстовый DSL)
enabled	boolean	Включено ли
hits7d	number	Срабатываний за 7 дней
author	string	Кто создал
createdAt	ISO 8601	Дата создания
cveoptional	string	Для виртуальных патчей: закрываемая уязвимость
productoptional	string	Для виртуальных патчей: уязвимый продукт
reasonoptional	string	Для исключений: причина создания

BotSignature сигнатура бота

Поле	Тип	Описание
id	ulid	Идентификатор сигнатуры
name	string	Название бота или семейства
class	'good' \| 'bad' \| 'suspicious'	Класс: полезный / вредоносный / подозрительный
action	'block' \| 'challenge' \| 'pass'	Действие при обнаружении
share	number	Доля в бот-трафике, %
requests24h	number	Запросов за последние 24 часа

Incident DDoS-инцидент

Поле	Тип	Описание
id	ulid	Идентификатор инцидента
domainId	ulid	Атакуемый домен
startedAt	ISO 8601	Начало атаки
endedAt	ISO 8601 \| null	Окончание; `null` — атака продолжается
peakRps	number	Пиковая нагрузка, запросов в секунду
status	'active' \| 'mitigated'	Статус: активен / отражён
vector	string	Вектор атаки
timeline	Array<{ ts, text }>	Таймлайн: отметки времени и что произошло

ApiEndpoint эндпоинт клиента (API Security)

Поле	Тип	Описание
id	ulid	Идентификатор записи
domainId	ulid	Домен, которому принадлежит эндпоинт
method	string	HTTP-метод
path	string	Путь эндпоинта
schemaMatch	number	Соответствие OpenAPI-схеме, доля 0…1
violations24h	number	Нарушений схемы за 24 часа
strict	boolean	Строгий режим: блокировать запросы вне схемы
shadow	boolean	Shadow-API: есть в трафике, но отсутствует в схеме

Certificate TLS-сертификат

Поле	Тип	Описание
id	ulid	Идентификатор сертификата
domainId	ulid	Домен, к которому привязан
host	string	Имя хоста в сертификате
issuer	string	Издатель
validFrom	ISO 8601	Действителен с
validTo	ISO 8601	Действителен до
auto	boolean	Автопродление включено
status	'valid' \| 'expiring' \| 'expired'	Статус: действителен / истекает / истёк
daysLeft	number	Дней до окончания срока

ApiToken токен интеграции

Поле	Тип	Описание
id	ulid	Идентификатор токена
name	string	Название (для чего создан)
scopes	string[]	Разрешённые области доступа
lastUsedAt	ISO 8601 \| null	Последнее использование; `null` — не использовался
createdAt	ISO 8601	Дата создания
prefix	string	Префикс ключа; полный секрет показывается один раз при создании

Invoice счёт

Поле	Тип	Описание
id	ulid	Идентификатор счёта
period	string	Расчётный период
amount	number	Сумма, ₽
status	'paid' \| 'pending' \| 'overdue'	Статус: оплачен / ожидает / просрочен
pdfUrl	string	Ссылка на PDF-версию счёта

Usage потребление ресурсов

Поле	Тип	Описание
trafficTb	number	Израсходовано трафика, ТБ
trafficLimitTb	number	Лимит трафика по тарифу, ТБ
domains	number	Подключено доменов
domainsLimit	number	Лимит доменов по тарифу
requests	number	Запросов за период
requestsLimit	number	Лимит запросов по тарифу
forecast	{ date, addTb, price } \| null	Прогноз исчерпания трафика: дата и стоимость докупки; `null` — перерасход не прогнозируется

Контракт также включает служебные сущности Session, Channel, NotificationRule, AuditEntry и Ticket — их подробное описание появится к публичному запуску.

Эндпоинты

Все пути указаны относительно базы https://api.webfas.ru/v1. Списочные эндпоинты поддерживают пагинацию и фильтры (см. Обзор). Сегменты вида :id — path-параметры (ULID).

Авторизация

Метод	Путь	Назначение
POST	/auth/register	Регистрация. Отвечает `202 { status: "verification_sent" }` одинаково для свободного и занятого адреса — по ответу нельзя проверить, есть ли аккаунт
POST	/auth/verify	Подтверждение почты по ссылке из письма; сразу открывает сессию
POST	/auth/resend-verification	Повторная отправка письма подтверждения
POST	/auth/login	Вход по e-mail и паролю; при включённой 2FA возвращает `{ twoFaRequired, challengeId }`
POST	/auth/2fa	Подтверждение входа кодом из приложения или резервным кодом вида `WF-XXXX-XXXX`
POST	/auth/refresh	Обмен httpOnly-cookie на новый токен запросов. Токен живёт 30 минут, cookie ротируется на каждом обмене
POST	/auth/recover	Запрос восстановления пароля; ответ одинаков независимо от существования адреса
GET	/auth/reset/check	Жива ли ссылка восстановления — до показа формы
POST	/auth/reset	Новый пароль по ссылке из письма. Закрывает все прежние сессии
POST	/auth/logout	Выход, отзыв текущей сессии

Профиль и сессии

Метод	Путь	Назначение
GET	/me	Текущий пользователь и аккаунт
PATCH	/me	Изменение профиля (имя, пароль, настройки 2FA)
GET	/me/sessions	Список активных сессий
DELETE	/me/sessions	Завершить все сессии, кроме текущей
PATCH	/me/password	Смена пароля; закрывает остальные устройства
GET	/me/2fa	Состояние второго фактора и остаток резервных кодов
POST	/me/2fa/init	Секрет и ссылка `otpauth://` для QR-кода
POST	/me/2fa/enable	Включение по коду из приложения; в ответе — десять резервных кодов, показываются один раз
POST	/me/2fa/codes	Перевыпуск резервных кодов (старые перестают работать)
POST	/me/2fa/disable	Отключение — тоже по коду: украденная сессия не снимет фактор

Домены

Метод	Путь	Назначение
GET	/domains	Список доменов аккаунта
POST	/domains	Добавить домен (начало онбординга)
GET	/domains/:id	Карточка домена
PATCH	/domains/:id	Изменить настройки: режим WAF, origin-IP и другое
DELETE	/domains/:id	Удалить домен из защиты
POST	/domains/:id/verify-dns	Проверить, что DNS-записи переключены на webfas
POST	/domains/:id/pause	Приостановить или возобновить защиту
POST	/domains/:id/cache/purge	Сбросить кэш домена

События безопасности

Метод	Путь	Назначение
GET	/events	Журнал событий: фильтры по периоду, домену, вердикту, типу атаки, поиск
GET	/events/:id	Деталка события: payload, JA4, ASN, гео
POST	/events/:id/exception	«Ложное срабатывание»: создаёт Rule с `kind = exception`
SSE	/events/stream	Живой поток событий и счётчиков — см. SSE-поток

Правила

Метод	Путь	Назначение
GET	/rules	Список правил: свои, исключения, виртуальные патчи
POST	/rules	Создать правило
GET	/rules/:id	Одно правило
PATCH	/rules/:id	Изменить правило, включить или выключить
DELETE	/rules/:id	Удалить правило
POST	/rules/preview	Предпросмотр по трафику за сутки → `{ matched24h, samples[] }`

Anti-Bot

Метод	Путь	Назначение
GET	/antibot/stats	Статистика: люди / полезные боты / вредоносные боты, временной ряд
GET	/antibot/signatures/:id	Сигнатура бота
PATCH	/antibot/signatures/:id	Изменить действие для сигнатуры: block / challenge / pass

DDoS-защита

Метод	Путь	Назначение
GET	/incidents	История DDoS-инцидентов
GET	/incidents/:id	Деталка инцидента с таймлайном
GET	/ddos/limits	Текущие лимиты: чувствительность, RPS на IP, burst
PUT	/ddos/limits	Обновить лимиты

API Security

Метод	Путь	Назначение
GET	/apisec/schemas	Загруженные OpenAPI-схемы
POST	/apisec/schemas	Загрузить OpenAPI-схему (YAML или JSON)
GET	/apisec/endpoints	Обнаруженные эндпоинты, включая shadow-API
PATCH	/apisec/endpoints/:id	Изменить настройки эндпоинта, включить строгий режим

Аналитика

Метод	Путь	Назначение
GET	/analytics/timeseries	Временной ряд: `?metric=&from=&to=&groupBy=`
GET	/analytics/breakdown	Разбивка по измерению: `?dim=` (тип атаки, страна, домен…)

Сертификаты

Метод	Путь	Назначение
GET	/certs	Список TLS-сертификатов
POST	/certs/:id/renew	Продлить сертификат сейчас
POST	/certs/upload	Загрузить собственный сертификат

Уведомления и каналы

Метод	Путь	Назначение
GET	/notifications/matrix	Матрица «событие × канал» и порог всплеска
PUT	/notifications/matrix	Обновить матрицу уведомлений
GET	/channels	Каналы доставки: e-mail, Telegram, webhook
POST	/channels	Подключить канал
DELETE	/channels/:id	Отключить канал

API-токены

Метод	Путь	Назначение
GET	/tokens	Список токенов интеграций
POST	/tokens	Создать токен; полный секрет возвращается один раз
DELETE	/tokens/:id	Отозвать токен

Биллинг

Метод	Путь	Назначение
GET	/billing/plan	Текущий тариф и дата следующего списания
GET	/billing/usage	Потребление ресурсов и прогноз перерасхода
GET	/billing/invoices	Счета с ссылками на PDF
POST	/billing/change-plan	Сменить тарифный план

Команда и журнал действий

Метод	Путь	Назначение
GET	/team	Участники команды
POST	/team	Пригласить участника
PATCH	/team/:id	Изменить роль участника
DELETE	/team/:id	Удалить участника
GET	/audit	Журнал действий с фильтрами

Поддержка

Метод	Путь	Назначение
GET	/tickets	Список тикетов
POST	/tickets	Создать тикет, опционально с привязкой к событию
GET	/tickets/:id	Тикет с перепиской
POST	/tickets/:id/messages	Написать сообщение в тикет

ИИ-консультант

Консультант по настройке защиты. Ключи провайдеров живут на сервере: клиент отправляет текст вопроса, ответ приходит потоком text/event-stream (события start, delta, done, error).

Метод	Путь	Назначение
GET	/assistant/config	Доступные модели, можно ли выбирать модель, остаток дневной квоты, заготовки вопросов
GET	/assistant/chats	Диалоги текущего пользователя
POST	/assistant/chats	Создать диалог
GET	/assistant/chats/:id	Диалог с историей сообщений
POST	/assistant/chats/:id/messages	Вопрос модели; ответ идёт потоком SSE
DELETE	/assistant/chats/:id	Удалить диалог

Мастер настройки

Метод	Путь	Назначение
GET	/wizard	Шаги ввода защиты в работу с прогрессом аккаунта
POST	/wizard/steps/:id	Отметить шаг: `todo`, `in_progress`, `done`, `skipped` (обязательные шаги не пропускаются)
POST	/wizard/reset	Начать мастер заново
GET	/wizard/tours	Обучающие туры по интерфейсу и их состояние
POST	/wizard/tours/:id	Отметить тур пройденным или отложенным

SSE-поток событий

Живая лента кабинета работает поверх стандартного Server-Sent Events. Откройте долгоживущее соединение — сервер будет присылать именованные события по мере их появления.

Эндпоинт

GET https://api.webfas.ru/v1/events/stream

Заголовки

Accept: text/event-stream, Authorization: Bearer <jwt>

Типы событий

security_event · counters · incident

event	data	Когда приходит
security_event	SecurityEvent	Новое событие безопасности: блокировка, челлендж или пропуск запроса
counters	{ requests, blocked, challenged, … }	Периодическое обновление суточных счётчиков для метрик-плиток
incident	Incident	Начало, обновление или завершение DDoS-инцидента

Пример потока:

event: security_event
data: {"id":"01J5X8…","ts":"2026-08-22T11:03:41Z","verdict":"blocked","attackType":"SQLi","path":"/catalog", …}

event: counters
data: {"requests":2412380,"blocked":38214,"challenged":4120}

event: incident
data: {"id":"01J5XA…","status":"active","peakRps":214000, …}

При обрыве соединения переподключайтесь с заголовком Last-Event-ID — сервер дошлёт пропущенные события в пределах окна ретрансляции.

Статус API

Часть API уже работает, часть — ещё нет. Отвечают разделы /auth, /me, /assistant и /wizard: они обслуживают личный кабинет. Разделы защиты трафика — домены, события, правила, Anti-Bot, DDoS, API Security, аналитика, биллинг — возвращают 501 not_implemented с заголовком Retry-After, пока не запущен обработчик трафика: так интеграция отличает «ещё не готово» от опечатки в пути. Отдельные поля и коды ошибок до открытия публичного доступа могут измениться. Ранний доступ — hello@webfas.ru.