Роли и разрешения API-ключей

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

Три роли#

Роль	Что она может делать
viewer	Просмотр ссылок, аналитики и настроек рабочего пространства. Не может ничего создавать, обновлять или удалять.
editor	Все, что может viewer, плюс создание/обновление/удаление ссылок, управление вебхуками и выполнение массового импорта.
admin	Все, что может editor, плюс управление участниками рабочего пространства, биллингом, API-ключами и правилами IP.

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

Какую роль использовать#

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

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

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

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

Сопоставление ролей и эндпоинтов#

Краткая справка по распространенным вызовам 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.

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