Ключи API и права доступа

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

Где получить ключ

Настройки платформы → Настройка системы → Интеграции. Этот экран платформы доступен Superuser. Серверные операции управления дополнительно проверяют права интеграций; наличие такого права у другой роли само по себе не открывает экран платформы. Выбор другого пользователя владельцем ключа ограничен Superuser.

1. Откройте вкладку «Доступ по API», перейдите к «Ключи доступа» и нажмите «Выдать ключ».
2. Укажите понятное название, владельца и будущую дату окончания.
3. Выберите только необходимые действия, например objects:read и metadata:read для чтения.
4. Сохраните полный ключ в хранилище секретов своей программы. Он показывается только при выдаче.
5. Проверьте чтение разрешённой записи и отказ на запрещённой.

Ключ — секрет

Не помещайте его в URL, исходный код, скриншот, почту или журнал запросов. При раскрытии отзовите ключ и выдайте новый. Короткая метка в списке не заменяет полный ключ.

Как передать

GET /api/v1/objects?page=1&pageSize=25 HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Вместо Authorization поддерживается X-API-Key: YOUR_API_KEY. Используйте один способ, а не оба одновременно. Ключ содержит tenant: заголовком нельзя переключить организацию.

Две независимые проверки

Проверка	Пример
Действие ключа	objects:write разрешает обращаться к командам записи
Права владельца	Может ли владелец создать данный тип и изменить конкретное поле

Нужны обе. * в scope не отменяет ограничения владельца. Блокировка пользователя, отзыв или истечение ключа прекращают доступ. Изменение прав применяется и к уже выданным ключам.

Отдельная учётная запись программы

Если интеграция не должна зависеть от личной учётной записи сотрудника, раскройте «Что такое учётная запись подключения?» → «Создать учётную запись». Введите название программы и нажмите «Создать без прав». Права назначаются отдельно в «Группы пользователей и роли»; само создание программы не даёт ей доступ к записям.

После назначения минимальных прав вернитесь к выдаче ключа и выберите программу в группе «Отдельные учётные записи программ». Для учётной записи также действуют обе проверки из таблицы выше.

Заменить ключ без резкого отключения

1. Найдите ключ по названию программы и владельцу. В «Что разрешено и как отличить ключ» видны действия и короткий идентификатор, но не секрет.
2. Нажмите «Заменить». Проверьте название и будущий срок. Владелец и разрешения сохраняются; это не способ расширить доступ.
3. Нажмите «Выпустить замену», проверьте подтверждение и сохраните новый секрет. Дата и время в форме относятся к часовому поясу браузера.
4. Установите новый ключ во внешней программе и проверьте её работу. Старый ключ пока продолжает действовать.
5. Вернитесь к старому ключу, нажмите «Отозвать» и подтвердите. Программы, в которых остался старый ключ, потеряют доступ. Отзыв необратим: вернуть прежний секрет нельзя.

Если ключ скомпрометирован, не ждите плановой замены: отзовите его сразу и согласуйте перерыв с владельцем интеграции. Поле «Последнее использование» помогает разбору, но само по себе не доказывает, что все потребители уже переключились.

Ограничения и ошибки

401 — ключ неверен, просрочен, отозван или его владелец неактивен. 403 — ключ распознан, но не хватает scope либо права на данные. Не лечите 403 выдачей всех прав: сначала определите запрещённую операцию.

Штатный API не предоставляет публичный метод обмена логина и пароля на ключ. Cookie пользовательского входа не заменяет ключ /api/v1.

Связанные статьи

• Первый запрос
• Ошибки и безопасные повторы
• Безопасность доступа