Сервисные аккаунты

Сервисным аккаунтом называется участник компании, от имени которого работает программа: интеграция, скрипт, коннектор к ассистенту. У него нет пароля, почты и сессии, в интерфейс он не входит. Он обращается к API с токеном, и все, что он делает, записывается в историю задач и в журнал компании под его именем.

Чем он отличается от человека#

Заводить общий аккаунт человека "для интеграции" не нужно: у такого аккаунта есть пароль, который кто-то знает, и место, которое он занимает. Сервисный аккаунт честно показывает в журнале, что действие сделала программа.

Как создать#

Сервисными аккаунтами управляет тот, у кого есть право компании "Настраивать сервисные аккаунты" (serviceaccounts.edit). У администраторов компании оно есть сразу.

1. Откройте Администрирование, раздел Сервисные аккаунты.
2. Нажмите "Создать сервисный аккаунт" и введите имя, по которому его узнают в журнале, например "Коннектор Claude".
3. Выдайте аккаунту роль в тех проектах, с которыми он будет работать: в участниках проекта или через группу.

Если компания уже использует все сервисные аккаунты, которые ей доступны, создание отклоняется с кодом identity.seats_exhausted. Место освобождает удаленный или деактивированный аккаунт.

Токены#

Токен выглядит как строка qvl_..., и программа передает его в каждом запросе:

Authorization: Bearer qvl_...

1. На карточке аккаунта нажмите "Выпустить токен".
2. Назовите токен так, чтобы через полгода было понятно, где он лежит, например "MCP production".
3. Выберите права токена: "Все права аккаунта" или "Выбранные права" (о них ниже).
4. Скопируйте значение и нажмите "Скопировано". Токен показывается один раз: мы храним только его хеш, показать его снова нельзя ни вам, ни нам.

У токена нет срока, он работает, пока его не отзовут. На карточке видно, когда токен выпущен и когда им пользовались в последний раз. Отозванный кнопкой "Отозвать" токен перестает работать со следующего запроса.

Токен выдан одной компанией и работает только на ее адресе: https://<ключ>.quevell.com/api. Запрос с этим токеном на адрес другой компании отклоняется с кодом auth.tenant_mismatch.

Чтобы сменить токен без перерыва, выпустите новый, переключите программу и отзовите старый. Токенов у аккаунта может быть несколько.

Права токена#

Токен никогда не может больше, чем аккаунт. "Все права аккаунта" значит ровно то, что аккаунт может в проектах сейчас. "Выбранные права" сужают токен до выбранных:

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

Список прав запоминается в токене, а роли аккаунта проверяются при каждом запросе. Если снять аккаунт с проекта или убрать из группы, уже выпущенный токен теряет этот доступ со следующего запроса, перевыпускать его не нужно.

Права самого аккаунта#

Роли в проектах аккаунт получает так же, как человек: напрямую или через группу. Группы удобны, когда одна интеграция работает с десятком проектов.

Права компании сервисному аккаунту не выдаются никак: ни напрямую, ни через группу. Администрировать компанию токеном нельзя. В группу "Полный доступ" сервисный аккаунт не добавляется, попытка отклоняется с кодом identity.service_account_not_administrator.

OAuth-клиенты#

Некоторые программы не принимают постоянный токен и сами получают временный по протоколу OAuth 2.0, например коннекторы ассистентов. Для них на карточке аккаунта есть "Создать OAuth-клиент".

1. Назовите клиента и выберите его права, так же как у токена.
2. Скопируйте client_id (вида qvc_...) и client_secret (вида qvs_...). Секрет показывается один раз.
3. Программа обменивает их на токен:

curl -X POST https://<ключ>.quevell.com/api/oauth/token \
  -u "qvc_...:qvs_..." \
  -d grant_type=client_credentials

В ответе access_token на 60 минут, token_type Bearer и expires_in. Токена обновления нет: когда час истек, программа снова обращается за токеном. Поддерживается только способ client_credentials. Любая ошибка в идентификаторе или секрете дает один и тот же ответ 401 invalid_client, чтобы по нему нельзя было подобрать половину пары.

Обмен ограничен: 10 токенов в минуту на одного клиента и 30 в минуту с одного адреса. Честной программе хватает одного обмена в час; сверх лимита ответ 429 с кодом oauth.rate_limited и заголовком Retry-After.

Токены, выданные клиентом, в списке токенов аккаунта не показываются: это не учетные данные, а их временные копии. Отзыв клиента отзывает и все токены, которые он выдал.

Деактивация и удаление#

Действие, которое не подходит к текущему состоянию аккаунта, отклоняется с кодом этого состояния: identity.service_account_deactivated, identity.service_account_active или identity.service_account_deleted.

После удаления то, что аккаунт сделал, остается в истории задач и в журнале компании под его прежним именем.

Лимиты#

Запросы сервисных аккаунтов ограничены по частоте и по числу записей в сутки: 120 вызовов в минуту на аккаунт, 600 на все аккаунты компании, 10 000 записей в сутки на аккаунт и 50 000 на компанию. Как считаются лимиты и что приходит в ответ при превышении, описано в разделе Лимиты статьи об API.