Дозволи ключів API

Дозволи ключів API визначають, що може зламати витеклий ключ. В інструменті посилань безпечне значення за замовчуванням - це ключ, прив'язаний до одного робочого простору, обмежений найнижчою роллю, достатньою для завдання, збережений як хеш із pepper, з окремим лімітом запитів і терміном дії. Ключ, що лише створює посилання, не має торкатися вебхуків, учасників чи білінгу, і ніколи не повинен відкривати адмінський ендпоінт. Це і є мінімальні привілеї, а більша частина зводиться до рішень, які ви ухвалюєте за ті тридцять секунд, що триває створення ключа.

Протягом минулого року я прочитав чимало налаштувань автоматизації, і шаблон повторюється: хтось у п'ятницю по обіді вставляє свій всемогутній ключ у n8n, воно працює, і ніхто більше про це не думає, доки ця людина не піде або експорт робочого процесу не опиниться на спільному диску. Решта допису розповідає, як працюють scope і ролі ключів API у продукті скорочення посилань, що насправді може кожна роль і як передати ключ інструменту автоматизації, не віддаючи робочого простору.

Допис доповнює наш ширший чекліст безпеки скорочувача посилань, який охоплює сканування, підпис вебхуків і журнали аудиту по всій платформі. Цей зосереджений на самому ключі.

Що означають дозволи ключів API в інструменті посилань

API інструмента посилань торкається не лише посилань. Той самий токен, що створює go.example.com/spring-sale, залежно від дозволів може читати аналітику кліків, додавати власний домен, запрошувати учасника або реєструвати вебхук, який шле кожну подію на сторонній сервер. Останнє мене лякає найбільше. Вебхук - це постійний потік даних, який той, хто його створює, може спрямувати на будь-який сервер, а ваша команда може не помічати цього тижнями.

Тому в дозволів три осі. Де працює ключ (який обліковий запис чи робочий простір)? Що він може там робити (читати, писати, адмініструвати)? І як довго та як швидко? Визначення мінімальних привілеїв у глосарії NIST (дата звернення 2026-10-24) каже, що кожна сутність отримує мінімум авторизацій, потрібних для виконання її функції, і всі три осі входять до цього. Ключ лише для читання, який ніколи не спливає й не має ліміту запитів, усе одно має надлишкові привілеї в часі.

Ключі API в межах робочого простору: один ключ, один робочий простір

В Elido кожен ключ створюється всередині робочого простору й там залишається. Якщо викликати з ним ендпоінти будь-якого іншого робочого простору, ви отримаєте 404, ту саму відповідь, що й для неіснуючого робочого простору, тож ключ навіть не може підтвердити, що інші робочі простори існують.

Це важливіше, ніж здається. Агенції та більші команди часто належать до п'яти чи десяти робочих просторів. Якби особистий ключ успадковував усе, до чого має доступ його творець, один витеклий токен з одного клієнтського проєкту відкрив би всіх клієнтів. Ключі API в межах робочого простору зменшують радіус ураження до одного робочого простору.

Ключ також обмежений роллю, обраною під час створення, і ніколи не перевищує поточну роль свого творця. Фактичний доступ - це менша з двох. Понизьте admin, який створив ключ, до editor. Ключ знижується разом із ним. Особливі дозволи, прикріплені до цього учасника, також відкидаються, якщо роль ключа нижча, бо вони описують людину, а не ключ.

Ключі API на основі ролей: що може кожна роль

Ключі Elido використовують ті самі чотири ролі, що й люди: viewer, editor, admin і owner. Ви обираєте одну під час створення ключа; якщо не вказати, ключ за замовчуванням отримує editor, що покриває звичайне завдання автоматизації - створювати посилання й читати аналітику без адмінського доступу.

Ось як це виглядає на практиці для того, чого зазвичай торкаються інтеграції.

Панелі звітності, що тягне кількість кліків у BI-інструмент, потрібен viewer. Завданню Google Sheets, яке створює кампанійні посилання, потрібен editor. Майже нічого в повсякденній автоматизації не потребує admin, а ключ owner я б вважав тривожною ознакою: owner існує для людей, що керують робочим простором, і я не можу уявити завдання автоматизації, якому він потрібен.

Варто знати два обмеження. Дозвіл api_keys.manage мають лише admin і owner, тож ключ viewer чи editor не може переглядати або відкликати ключі. А створення ключа чи зміна його ліміту запитів потребує людини з входом у систему: ключ API будь-якої ролі отримує 403 («this action requires an interactive session»). Витеклий ключ admin не може створити безстроковий замінник. Але може переглядати й відкликати ключі. І жоден ключ будь-якої ролі не сягає адмінського API платформи. Ця поверхня відмовляє автентифікації ключем API одразу з кодом 403 і повідомленням «admin access requires an interactive session». Ключ призначений для інтеграції з робочим простором, і більше нічого він не відкриває.

Чому керування вебхуками потребує ключа admin

Саме це дивує людей найбільше. Читати список ендпоінтів вебхуків дозволено будь-якому учаснику, зокрема ключам viewer. Але створення ендпоінта, зміна його адреси чи replay доставки вимагають дозволу workspace.edit, який мають лише admin і owner.

Міркування - у проблемі постійного потоку, згаданій раніше. Editor може створити тисячу посилань, і ви це помітите. Editor, який міг би додати універсальний вебхук на власний сервер, відтоді мовчки отримував би кожну подію посилань. Тому зміни вебхуків залишено тим самим людям, що можуть змінювати налаштування робочого простору.

На практиці налаштуйте вебхуки один раз вручну як admin у панелі. Потім дайте автоматизації, що їх споживає, ключ 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 запитів на секунду, а burst - від 1 до 20 000, або скинути перевизначення, щоб повернутися до значення за замовчуванням. Після перевищення ліміту ключ отримує 429 із Retry-After: 1 і X-RateLimit-Scope: api_key, тож ваша логіка повторів відрізнить ліміт ключа від ліміту робочого простору. Як правильно відступати, описано в посібнику про ліміти запитів та ідемпотентність.

Термін дії необов'язковий і задається під час створення як мітка часу RFC 3339. Коли він минув, ключ просто перестає збігатися. Відкликання - один DELETE. Він також ідемпотентний.

Єдиної кнопки «ротувати» немає, і я за нею не сумую. Ротація складається з трьох кроків:

1. Створіть новий ключ із тією самою роллю та новим терміном дії.
2. Підмініть його в сховищі облікових даних інструмента й переконайтеся, що виклик успішний.
3. Відкличте старий ключ, а потім перевірте в списку, що час його останнього використання перестав змінюватися.

Кожен крок потрапляє в журнал аудиту робочого простору: api_key.created з іменем і роллю, api_key.revoked та api_key.rate_limit_set для перевизначень. Фонове сканування також запускається кожні п'ять хвилин і позначає будь-який ключ, що має понад 1000 запитів, з яких понад 30% невдалі. Позначка потрапляє в журнал аудиту й на ключ. Автоматичного відкликання немає. Вимкнення ключа - рішення людини, бо сплеск 404 так само часто означає зламаний робочий процес, як і зловмисника.

Передача ключів API з мінімальними привілеями в n8n, Make і Zapier

Платформи автоматизації - місце, де ключі йдуть, щоб бути забутими. Вони лежать у сховищі облікових даних, копіюються в експортований JSON робочих процесів і переживають людину, що їх налаштувала. Допомагають дві звички:

• Один ключ на інструмент і на сімейство робочих процесів, названий за ним («n8n: campaign sheets»). Тоді відкликання ламає рівно одну річ, а журнал аудиту показує, який інструмент що робив.
• Editor для всього, що створює посилання, viewer для всього, що лише читає, і дата спливання на обох.

На цьому список закінчується; решта - судження. Шпаргалка OWASP з керування секретами (дата звернення 2026-10-24) добре розповідає, як тримати токени поза логами й експортами, де ключі автоматизації зазвичай і витікають.

Щодо налаштування для конкретних інструментів: посібник про n8n і скорочувач URL кладе ключ у облікові дані Header Auth, а порівняння Make, IFTTT, n8n і Zapier показує, де кожна платформа його зберігає. Zapier підключається через той самий токен, як у покроковому описі автоматизації Zapier. Для CI чи всього, що має пережити звільнення людини, краще підходить машинний користувач: сервісний обліковий запис із власним токеном, окремим від ключа будь-якої людини. Як і ключі, машинних користувачів створює адмін із входом у систему, але не токен.

І причина, чому ключ ніколи не повинен відкривати адмінські ендпоінти, - саме ця передача. Коли токен лежить у стороннього інструмента, ним може скористатися кожен, хто має право редагувати робочі процеси цього інструмента. Ви довіряєте всім на їхньому боці, а не лише на своєму.

Токени з окремими scope заплановані, але ще не діють

Ролі навмисно грубі, а подекуди надто грубі. Ключ editor, що лише створює посилання, може їх і видаляти, бо видалення входить до ролі editor. Виправлення - токени з окремими scope, як-от links:write чи analytics:read, прикріплені безпосередньо до ключа поверх ролей.

Це є в нашому плані, але не випущено. Сьогодні дозволи ключа - це його робочий простір плюс роль, і нічого дрібнішого. Якщо контроль потрібен жорсткіший уже зараз, важелів два: нижча роль і короткий термін дії, а також окремі ключі на кожне завдання, щоб радіус ураження кожного був малим. Швидкий старт з API і довідник API та SDK показують поточну модель ключів у робочому коді, а команди, яким потрібен контроль на рівні ідентичності, можуть прочитати про SCIM і SSO для маркетингових інструментів.

Читайте опорну статтю: чекліст безпеки скорочувача посилань охоплює засоби контролю навколо ключа, від сканування URL до списків дозволених IP.

Пов'язане в блозі

• API скорочувача URL: швидкий старт за 30 хвилин п'ятьма мовами
• n8n і скорочувач URL: вузол HTTP Request чи community-вузол Elido
• Автоматизація коротких посилань: Make, IFTTT, n8n чи Zapier
• Вебхуки для подій посилань
• GitHub Actions і скорочувач URL: короткі посилання з вашого CI