Ролі та дозволи API-ключів

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

Три ролі#

Роль	Що вона може робити
viewer	Читання посилань, аналітики та налаштувань робочого простору. Не може нічого створювати, оновлювати або видаляти.
editor	Усе, що може viewer, плюс створення/оновлення/видалення посилань, керування вебхуками та виконання масового імпорту.
admin	Усе, що може editor, плюс керування учасниками робочого простору, білінгом, API-ключами та правилами IP.

Ви встановлюєте роль під час створення ключа в Settings → API keys. Ви не можете змінити роль ключа після його створення — випустіть новий ключ із правильною роллю та анулюйте старий.

Яку роль використовувати#

Панелі аналітики та інтеграції лише для читання — використовуйте viewer. Сторонній BI-інструмент, сторінка статусу, що отримує кількість кліків, або внутрішній скрипт звітності потребують лише читання даних.

CI/CD конвеєри, які скорочують посилання — використовуйте editor. Сюди відносяться ваші скрипти розгортання, що створюють посилання для кампаній, інтеграція з CMS для генерації коротких URL та більшість автоматизацій Zapier/Make.

Автоматизація адміністрування — використовуйте admin лише тоді, коли інтеграції справді потрібно керувати учасниками або білінгом. Це трапляється рідко. Більшість інтеграцій, які «здаються адміністративними», насправді є просто editor.

MCP сервер / AI агент — editor є правильним вибором за замовчуванням, якщо агенту не потрібно запрошувати учасників. Пакет @elido/mcp-server враховує роль ключа.

Role-to-endpoint mapping#

Швидка довідка для поширених API-викликів:

GET    /v1/links              → viewer
POST   /v1/links              → editor
PUT    /v1/links/:id          → editor
DELETE /v1/links/:id          → editor
GET    /v1/analytics/clicks   → viewer
GET    /v1/workspace          → viewer
POST   /v1/workspace/members  → admin
POST   /v1/api-keys           → admin

Повна довідка доступна за посиланням /api.

Помилки невідповідності області доступу#

Якщо ключ не має дозволу для ендпоінтів, API повертає:

{
  "error": "forbidden",
  "message": "this key requires the admin role to manage workspace members",
  "required_role": "admin",
  "key_role": "editor"
}

Поле required_role підкаже вам, що саме потрібно. Вирішення полягає у випуску нового ключа з вищою роллю (якщо це зроблено навмисно) або в перегляді того, чи повинна інтеграція взагалі виконувати цю операцію.

Поширені помилки:

• Використання ключа viewer для створення посилань. Рішення: випустіть ключ editor.
• Використання ключа editor для запрошення учасника команди зі скрипта. Рішення: випустіть ключ admin або скористайтеся панеллю керування.
• Плутанина між роллю учасника на рівні робочого простору (Owner/Member) та роллю API-ключа. Це окремі поняття. Учасник команди з доступом «Member» все одно може створити API-ключ із роллю admin для власних інтеграцій — дозволи його панелі керування не успадковуються ключем.

Усунення несправностей#

403 на ендпоінті, який має бути дозволеним. Перевірте роль ключа в Settings → API keys — вона вказана в колонці Role. Якщо роль виглядає правильною, переконайтеся, що ви надсилаєте заголовок Authorization: Bearer <token>, а не заголовок Basic auth або параметр запиту.

401 Unauthorized. Ключ або анульовано, або токен неправильний. Перевірте колонку Status на наявність значка revoked. Якщо ключ активний, переконайтеся, що ви скопіювали повний токен під час створення.

Ключ працює для читання, але не працює для запису. Ваш ключ, ймовірно, має роль viewer. Випустіть новий ключ editor.

Мені потрібні різні дозволи для кожної інтеграції. Випускайте по одному ключу на інтеграцію. Створення ключів безкоштовне, і їх легко анулювати окремо, тому немає причин ділити один ключ між двома системами.