Права API-ключа определяют, что может сломать утёкший ключ. В ссылочном сервисе безопасный вариант по умолчанию - ключ, привязанный к одному рабочему пространству, ограниченный самой низкой ролью, достаточной для работы, хранящийся как хеш с pepper, имеющий собственный лимит запросов и срок действия. Ключу, который только создаёт ссылки, нечего делать с вебхуками, участниками или биллингом, и он никогда не должен открывать административный эндпоинт. Это и есть принцип наименьших привилегий, и почти всё сводится к выбору, который вы делаете за тридцать секунд создания ключа.
За последний год я просмотрел немало настроек автоматизации, и картина повторяется: кто-то в пятницу вечером вставляет в n8n собственный ключ со всеми правами, всё работает, и о нём никто не вспоминает, пока этот человек не уйдёт или экспорт рабочего процесса не окажется на общем диске. В остальной части материала разобрано, как устроены области и роли API-ключей в сервисе коротких ссылок, что реально может каждая роль и как передать ключ инструменту автоматизации, не отдавая рабочее пространство целиком.
Материал дополняет наш общий чек-лист безопасности сервиса коротких ссылок, где рассматриваются сканирование, подпись вебхуков и журналы аудита по всей платформе. Здесь мы приближаем взгляд к самому ключу.
Что означают права API-ключа в ссылочном сервисе
API сервиса ссылок затрагивает больше, чем ссылки. Тот же токен, что создаёт go.example.com/spring-sale, в зависимости от прав может читать аналитику кликов, добавлять собственный домен, приглашать участника или регистрировать вебхук, отправляющий каждое событие на внешний сервер. Последнее меня пугает больше всего. Вебхук - это постоянный поток данных, который создавший его человек может направить на любой сервер, и никто в вашей команде не обязательно заметит это неделями.
Поэтому у прав три оси. Где работает ключ (какой аккаунт или рабочее пространство)? Что он может делать там (читать, писать, администрировать)? И как долго и с какой скоростью? Определение наименьших привилегий в глоссарии NIST (дата обращения 2026-10-24) говорит, что каждая сущность получает минимум полномочий, необходимых для выполнения её функции, и все три оси входят в это понятие. Ключ только для чтения, который никогда не истекает и не имеет лимита запросов, всё равно избыточно привилегирован во времени.
API-ключи на уровне рабочего пространства: один ключ, одно пространство
В Elido каждый ключ выпускается внутри рабочего пространства и остаётся в нём. Если вызвать им эндпоинты другого рабочего пространства, вы получите 404, такой же ответ, как для несуществующего пространства, так что ключ не может даже подтвердить, что другие пространства существуют.
Это важнее, чем кажется. Агентства и крупные команды часто состоят в пяти или десяти рабочих пространствах. Если бы личный ключ наследовал всё, до чего может дотянуться его создатель, один утёкший токен из проекта одного клиента открыл бы всех клиентов. Ключи на уровне рабочего пространства сужают радиус поражения до одного пространства.
Ключ также ограничен ролью, выбранной при создании, и никогда не превышает текущую роль своего создателя. Фактический доступ - меньший из двух. Понизьте администратора, создавшего ключ, до редактора, и ключ понизится вместе с ним. Индивидуальные разрешения, назначенные этому участнику, тоже отбрасываются, когда роль ключа ниже, потому что они описывают человека, а не ключ.
API-ключи по ролям: что может каждая роль
Ключи Elido используют те же четыре роли, что и люди: viewer, editor, admin и owner. Вы выбираете роль при создании ключа; если не указать, ключ по умолчанию получает editor, что покрывает обычную задачу автоматизации - создавать ссылки и читать аналитику без административных прав.
Вот как это выглядит на практике для того, чего обычно касаются интеграции.
| Роль | Ссылки и кампании | Аналитика | Вебхуки | Домены, участники, ключи |
|---|---|---|---|---|
| viewer | Только чтение | Чтение, запуск заданий экспорта CSV | Список эндпоинтов | Просмотр доменов и участников |
| editor | Создание, правка, удаление, массовое создание | Чтение, запуск заданий экспорта CSV | Список эндпоинтов | Просмотр доменов и участников |
| admin | Всё, что может editor | Плюс настройка экспорта данных в S3, плановые отчёты по email | Создание, изменение, повторная отправка | Управление доменами, участниками, ключами |
| owner | Всё | Всё | Всё | Всё |
Панели отчётов, которая загружает число кликов в BI-инструмент, нужен viewer. Заданию в Google Sheets, создающему ссылки кампаний, нужен editor. Почти ничему в повседневной автоматизации не нужен admin, а ключ owner я считаю тревожным признаком: owner существует для людей, управляющих рабочим пространством, и я не могу придумать задачу автоматизации, которой он был бы нужен.
Стоит знать два ограничения. Право api_keys.manage есть только у администраторов и владельцев, поэтому ключ viewer или editor не может ни перечислять, ни отзывать ключи. А создание ключа или изменение его лимита запросов требует человека с выполненным входом: API-ключ любой роли получает 403 («this action requires an interactive session»). Утёкший ключ admin не сможет выпустить бессрочную замену. Но он по-прежнему может перечислять и отзывать ключи. И ни один ключ любой роли не достаёт до административного API платформы. Эта поверхность напрямую отказывает в аутентификации по API-ключу ответом 403 и сообщением «admin access requires an interactive session». Ключ предназначен для интеграции рабочего пространства, и только её он и открывает.
Почему управление вебхуками требует ключа admin
Именно это удивляет людей. Читать список эндпоинтов вебхуков разрешено любому участнику, включая ключи viewer. Но создание эндпоинта, изменение его адреса или повторная отправка доставки требуют права workspace.edit, которое есть только у admin и owner.
Причина - проблема постоянного потока, о которой говорилось выше. Если editor создаст тысячу ссылок, вы это заметите. А если editor сможет добавить универсальный вебхук, направленный на собственный сервер, он с этого момента будет молча получать каждое событие по ссылкам. Поэтому изменения вебхуков отданы тем же людям, которые могут менять настройки рабочего пространства.
На практике настройте вебхуки один раз, вручную, в роли администратора в панели. Затем дайте автоматизации, которая их обрабатывает, ключ editor или viewer для её вызовов API. Если вы подключаете вебхуки событий ссылок к Slack или CRM, принимающей стороне ключ Elido вообще не нужен; ей нужен секрет подписи для проверки данных.
Хотите доказательство, прежде чем что-то подключать? Создайте бесплатное рабочее пространство, выпустите ключ viewer и ключ editor и попробуйте одинаковый вызов записи каждым. Ответ 403 на ключ viewer объяснит больше любой таблицы.
Как хранятся ключи: pepper, хеш и префикс
Токен выглядит как elido_, за которым идут 52 символа base32, сгенерированные из 32 случайных байт. Вы видите его целиком ровно один раз, в ответе на вызов создания. После этого с нашей стороны он исчезает навсегда.
Мы храним HMAC-SHA256 токена с ключом в виде серверного pepper, который лежит в конфигурации приложения, а не в базе данных. При каждом запросе входящий Bearer-токен (схема, определённая в RFC 6750, дата обращения 2026-10-24) хешируется так же, и поиск идёт по хешу. Так что украденный дамп базы данных - это список хешей, которые никто не может проверить без pepper. Нет pepper - нет запуска: промышленный сервис отказывается стартовать, если он не задан.
Для ваших записей мы храним первые восемь символов после elido_ как отображаемый префикс, а страница API-ключей показывает этот префикс рядом с именем ключа, его ролью, датой создания, сроком действия, временем последнего использования и IP последнего использования, а также общее число запросов и число неудачных. Когда ключ обнаруживается где-то в логе, префикс подсказывает, какой это ключ. Никому не нужно видеть полный секрет.
Лимиты запросов, срок действия и ротация API-ключей
У каждого ключа своя корзина токенов (token bucket), отдельная от лимита рабочего пространства, поэтому один вышедший из-под контроля рабочий процесс не съест бюджет всего остального. Администратор с выполненным входом может переопределить скорость отдельного ключа от 1 до 10 000 запросов в секунду и всплеск от 1 до 20 000, либо снять переопределение и вернуться к значению по умолчанию. При превышении лимита ключ получает 429 с Retry-After: 1 и X-RateLimit-Scope: api_key, так что ваша логика повторов отличает лимит ключа от лимита рабочего пространства. Руководство по лимитам и идемпотентности рассказывает, как правильно делать паузы между повторами.
Срок действия необязателен и задаётся при создании как метка времени по RFC 3339. Когда он проходит, ключ просто перестаёт совпадать. Отзыв выполняется одним DELETE. Он тоже идемпотентен.
Единой кнопки «ротация» нет, и мне её не хватает. Ротация - это три шага:
- Создайте новый ключ с той же ролью и новым сроком действия.
- Подставьте его в хранилище учётных данных инструмента и убедитесь, что вызов проходит.
- Отзовите старый ключ, затем проверьте по списку, что время его последнего использования перестало меняться.
Каждый шаг попадает в журнал аудита рабочего пространства: api_key.created с именем и ролью, api_key.revoked и api_key.rate_limit_set для переопределений. Кроме того, каждые пять минут фоновая проверка помечает любой ключ, у которого больше 1 000 запросов и более 30% из них неудачные. Пометка попадает в журнал аудита и на сам ключ. Автоматического отзыва нет. Отключение ключа - решение человека, потому что всплеск 404 так же часто означает сломанный рабочий процесс, как и злоумышленника.
Передача ключей с наименьшими привилегиями в n8n, Make и Zapier
Платформы автоматизации - это места, где ключи забывают. Они лежат в хранилище учётных данных, копируются в экспортированный JSON рабочих процессов и переживают человека, который их настроил. Помогают две привычки:
- Один ключ на инструмент и на семейство рабочих процессов, названный по нему («n8n: campaign sheets»). Отзыв ломает тогда ровно одну вещь, а журнал аудита показывает, какой инструмент что сделал.
- Editor для всего, что создаёт ссылки, viewer для всего, что только читает, и срок действия у обоих.
На этом список заканчивается, остальное - суждение. Памятка OWASP по управлению секретами (дата обращения 2026-10-24) хорошо описывает, как не допускать токены в логи и экспорты, а именно там ключи автоматизации обычно и утекают.
Для настройки под конкретный инструмент руководство по n8n помещает ключ в учётные данные Header Auth, а сравнение Make, IFTTT, n8n и Zapier показывает, где хранит его каждая платформа. Zapier подключается через тот же токен, как показано в разборе автоматизации Zapier. Для CI или всего, что должно пережить уход человека, лучше подходит машинный пользователь: сервисный аккаунт с собственным токеном, отдельным от ключа любого человека. Как и ключи, машинных пользователей создаёт администратор с выполненным входом, но никогда не токен.
А причина, по которой ключ никогда не должен открывать административные эндпоинты, - именно эта передача. Когда токен лежит в сторонней системе, им может воспользоваться любой, у кого есть право редактировать её рабочие процессы. Вы доверяете всем на той стороне, а не только своим.
Токены с областями запланированы, но пока не работают
Роли намеренно грубые, и иногда слишком грубые. Ключ editor, который всегда только создаёт ссылки, может их и удалять, потому что удаление входит в роль editor. Решение - токены с областями вроде links:write или analytics:read, привязанные непосредственно к ключу поверх ролей.
Это в нашем плане развития, но не выпущено. Сегодня права ключа - это его рабочее пространство плюс роль, и ничего тоньше. Если нужен более строгий контроль уже сейчас, есть два рычага: более низкая роль и короткий срок действия, а также отдельные ключи на каждую задачу, чтобы радиус поражения каждого был небольшим. Быстрый старт по API и справочник по API и SDK показывают нынешнюю модель ключей на рабочем коде, а командам, которым нужен ещё и контроль на уровне удостоверений, пригодится материал про SCIM и SSO для маркетинговых инструментов.
Читайте материал-основу: чек-лист безопасности сервиса коротких ссылок охватывает меры вокруг ключа, от сканирования URL до списков разрешённых IP.
Читайте также в блоге
Частые вопросы
Что такое права API-ключа?
Это набор действий, которые ключу разрешено выполнять в API: какие ресурсы он может читать, какие менять и в каком аккаунте. В Elido права ключа определяются рабочим пространством, в котором он выпущен, и ролью, выбранной при создании, поэтому тот же ключ не может действовать в другом рабочем пространстве или выше этой роли.
Что такое принцип наименьших привилегий для API-ключей?
Это значит, что каждый ключ получает минимальный набор прав, необходимый для его задачи, и ничего сверх. Панели, которая только читает число кликов, достаточно ключа viewer, рабочему процессу, создающему ссылки, нужен ключ editor, а ключи admin оставляют для редких задач по управлению вебхуками, доменами или участниками. Тогда утёкший ключ сможет делать только то, что делала его единственная задача.
Чем отличаются области (scopes) API-ключа от ролей?
Область - это узкое разрешение вроде links:write, привязанное непосредственно к токену, а роль - именованный набор разрешений вроде editor. Роли проще понимать, области - тоньше. Ключи Elido сегодня используют роли рабочего пространства, а токены с областями запланированы поверх них, но ещё не работают.
Как часто нужно менять API-ключи?
Обычная рекомендация - раз в 30-90 дней, а также сразу, если ушёл человек, видевший ключ, ключ попал в лог или его трафик выглядит странно. Срок действия, заданный при создании, превращает это расписание в жёсткую остановку вместо календарного напоминания, которое все игнорируют.
Может ли API-ключ обращаться к административным эндпоинтам?
В Elido нет. Административный API платформы принимает только интерактивную сессию с входом в систему и отвечает на API-ключ кодом 403, какой бы ни была роль создавшего его человека. Настройки рабочего пространства, требующие прав администратора, остаются доступны, но только ключу, созданному с ролью admin или owner.
Как провайдер должен хранить API-ключи на своей стороне?
Никогда в открытом виде. Провайдер должен хранить хеш токена с ключом и после создания показывать только короткий префикс, чтобы одной копии базы данных было недостаточно для вызова API. Elido хеширует каждый токен через HMAC-SHA256 с серверным pepper и показывает полный токен ровно один раз.
Попробуйте Elido
Вставьте URL - получите короткую ссылку
Без регистрации. Ссылка живёт 30 дней. Зарегистрируйтесь, чтобы оставить её навсегда.
Без регистрации. Зарегистрируйтесь бесплатно и получите 50 ссылок в месяц.