Как мы проектируем ключи синхронизации

2026-10-20 · команда SyncHub

Ключ — единственный секрет клиента в Client Sync API. По нему отдаётся весь контент, поэтому требования к нему мы формулировали как к полноценному механизму доступа, а не как к «длинной строке в базе».

Непрозрачность

В ключе нет семантики: ни идентификатора клиента, ни даты выпуска, ни тарифа. Утечка ключа не раскрывает ничего, кроме самого факта доступа. Служебный префикс фиксированной длины нужен только нам — им удобно урезать ключ в логах поддержки до узнаваемого, но неполного вида.

Ключ живёт в path

Ключ передаётся в сегменте пути (/api/v1/sync/<key>), а не в query-параметре. Так он не попадает в заголовки вроде Referer, а урезанный путь в access-логах читается одинаково для всех клиентов. Query мы оставили параметрам устройств и каналов: did и feed.

Привязка устройства

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

Лимит — на ключ, а не на адрес

Мы ограничиваем 60 запросов в минуту на ключ. Лимит по IP-адресу для мобильного сценария бесполезен: у оператора за NAT-адресом — тысячи устройств, а у офиса — вся команда клиента. Пер-ключевая квота честнее: превышение — ошибка 429 и заголовок Retry-After.

Отзыв

Отзыв моментальный: отозванный ключ получает 403 при следующем запросе. Перевыпуск — через поддержку; старый ключ при этом отзывается сразу, параллельной жизни двух ключей у одного клиента мы сознательно не делаем — меньше живых секретов, меньше путаницы в логах.

Вопросы о безопасности ключей — support@synchub.example. Контракт целиком — в документации.