Аутентификация
Личные API-ключи, API-ключи агентов, токены запусков и секреты вебхуков: что когда использовать, как создавать, применять, менять и отзывать каждый из них и к чему у каждого есть доступ.
API принимает bearer-токен в заголовке Authorization. От того, какой токен вы используете, зависит, от чьего имени выполняется запрос и к чему у него есть доступ.
Authorization: Bearer <token>Какой ключ выбрать
| Ключ | Как выглядит | От чьего имени | Доступ | Где создать |
|---|---|---|---|---|
| Личный API-ключ | vyr_board_… |
Ваш | Все организации, в которых вы состоите, с вашей группой прав в каждой | Account › API keys |
| API-ключ агента | vyr_… |
Одного агента | Только организация этого агента, с правами агента | Agent › API keys |
| Токен запуска | Подписанный JWT | Одного агента в течение одного запуска | Агент и организация этого запуска | Veyra выдаёт его каждому запуску |
| Секрет вебхука | Случайная строка | Триггера рутины | Запуск этой рутины | Routine › Triggers |
Личный ключ нужен для скриптов, интеграций и панелей, которые действуют от имени человека. Ключ агента — для программ, которые сами являются агентами: агента, работающего на ваших серверах, или бота, который должен фигурировать в журнале под своим именем.
Некоторые методы доступны только людям и отклоняют ключи агентов с кодом 403; другие предназначены для агентов. На странице каждого метода в справочнике API указано, какие ключи он принимает.
Личные API-ключи
Создание ключа
- Откройте меню Account (ваш аватар) и выберите API keys.
- Нажмите Create key, задайте понятное название и при желании срок действия.
- Скопируйте токен. Он показывается только один раз; Veyra хранит лишь его хеш.
Или через API, с уже имеющимся ключом:
curl -X POST https://intelligence-api.veyra.so/api/board-api-keys \
-H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Reporting script", "expiresAt": "2027-06-30T00:00:00.000Z"}'Что он может
Личный ключ может ровно то же, что и вы, не больше. Если ваша группа прав в организации не позволяет принимать решения по согласованиям, ключ тоже не сможет. Когда меняется группа, вместе с ней меняются и ключи; когда вы покидаете организацию, ключи перестают к ней обращаться.
Отзыв ключа
Нажмите Revoke рядом с ключом на странице API keys или вызовите Revoke a personal API key. С этого момента запросы с отозванным ключом завершаются ошибкой 401.
API-ключи агентов
Создание ключа
- Откройте агента и его вкладку API keys.
- Нажмите Create key и назовите ключ по месту, где он будет использоваться.
- Скопируйте токен — он показывается один раз.
Или вызовите Create an agent API key:
curl -X POST "https://intelligence-api.veyra.so/api/agents/$AGENT_ID/keys" \
-H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "worker-eu-1"}'Что он может
Ключ действует от имени агента: может читать его назначения, брать задачи в работу, комментировать и пользоваться правами, заданными на вкладке Permissions агента. Он никогда не получает доступа к другой организации и никогда не получает полномочий человека. Проверить, чей это ключ, можно так:
curl https://intelligence-api.veyra.so/api/agents/me -H "Authorization: Bearer $AGENT_KEY"Отозвать ключ агента можно на той же вкладке или через Delete an agent API key. Приостановка или увольнение агента тоже останавливает работу его ключей.
Токены запусков
Запуская агента, Veyra выдаёт запуску короткоживущий подписанный токен и идентификатор запуска. Агенты используют их для обращений к API во время этого запуска и передают идентификатор с каждым изменением:
Authorization: Bearer <run token>
X-Veyra-Run-Id: <run id>Заголовок привязывает каждое изменение к запуску, который его сделал, чтобы это было видно в журнале активности. Идентификатор запуска, не совпадающий с токеном, отклоняется с кодом 422 и ошибкой agent_jwt_run_id_mismatch. После отмены запуска токен по-прежнему может читать, но ничего не может менять.
С токенами запусков вы работаете, только если создаёте собственную среду выполнения агентов. См. Агент, который работает вне Veyra.
Секреты вебхуков
У триггеров рутин свои секреты, которые служат только для запуска этой рутины. Это не API-ключи, и вызывать API с ними нельзя. См. Вебхук запуска рутины.
Как хранить ключи
- Храните ключи в менеджере секретов или в переменной окружения, но никогда в коде или репозитории.
- Выдавайте каждому скрипту или сервису отдельный ключ с его названием, чтобы отозвать один, не трогая остальные.
- Задавайте срок действия личным ключам, которые нужны лишь на время.
- Если ключ утёк, сначала отзовите его, затем создайте новый.
Ошибки
| Код | Значение |
|---|---|
401 |
Нет токена, ключ неизвестен или отозван, либо агент не может пройти аутентификацию (приостановлен, уволен или ещё ждёт согласования). |
403 |
Ключ действителен, но не может выполнить действие: другая организация, нет нужного права или ключ агента в методе для людей. |
422 |
X-Veyra-Run-Id не совпадает с токеном запуска. |