Авторизация по API-ключу

API-ключ — постоянный секрет, с которым ваша система вызывает методы маркетплейса от имени сотрудника, выпустившего ключ. Подходит для серверных скриптов, выгрузок и интеграций, которые работают без участия человека.

Ключ передаётся в заголовке Authorization:

Authorization: Bearer ВАШ_API_КЛЮЧ

Что нужно знать

• Ключ принадлежит пользователю, а не организации. Запрос с ключом выполняется от лица владельца, с теми ролями и разрешениями, что есть у него в организации сейчас. Лишить сотрудника роли — значит лишить прав и все его ключи.
• Ключ подходит ко всем методам API Reference, в том числе к получению ID организации.
• Полный ключ показывается один раз — сразу при выпуске. Восстановить его потом нельзя: у нас хранится только необратимый хеш. Потеряли ключ — отзовите его и выпустите новый.
• Ключом нельзя выпустить или отозвать другой ключ. Управление ключами доступно только из личного кабинета.

Как выпустить ключ

1. Войдите в личный кабинет и откройте меню профиля.
2. Нажмите API-ключи, затем Выпустить ключ.
3. Заполните форму (параметры — в таблице ниже) и подтвердите выпуск.
4. Скопируйте показанный ключ и сохраните его в менеджере секретов вашей системы.

Параметры ключа

Поле формы	Обязательно	Описание
Название	да	Метка, по которой вы отличите ключ в списке, например «Интеграция с 1С». До 100 символов
Срок действия	нет	«Бессрочный» (по умолчанию) — ключ действует, пока его не отзовут, или «Ограничить» — срок в днях от 1 до 365
Организации	нет	«Все мои организации» (по умолчанию) или «Выбрать организации» — до 50 штук, в которых ключ работает
Права	нет	«Все» (по умолчанию) или «Выбрать права» — какие группы методов доступны ключу

Права ключа не расширяют права владельца: даже если ключу разрешены сделки и выплаты, а у сотрудника нет права проводить выплаты в организации, метод вернёт 403.

Выдавайте минимум

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

Как использовать ключ

1. Узнайте organisationId нужной организации — Получение ID организации.

2. Вызывайте методы маркетплейса, подставив organisationId в URL:

   curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/<ORGANISATION_ID>/offers/filter" \
   --header "Authorization: Bearer ВАШ_API_КЛЮЧ" \
   --header "Content-Type: application/json" \
   --data '{ "filters": [], "pagination": { "limit": 20, "lastId": null } }'

Дальнейший сценарий работы описан в Быстром старте.

Управление ключами

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

• Отзыв. Нажмите Отозвать у нужного ключа и подтвердите: он перестанет приниматься сразу, без задержки. Отозванный ключ вернуть нельзя — выпустите новый.
• Лимит. У одного пользователя может быть не больше 20 действующих ключей. Отозванные и истёкшие ключи в лимит не входят.
• Ротация. Выпустите новый ключ, переключите на него интеграцию, затем отзовите старый. Отдельный ключ на каждую интеграцию упрощает ротацию и разбор инцидентов.

Ключи перестают работать автоматически, если владельца заблокировали или удалили. Заблокированный сотрудник теряет доступ по всем своим ключам, отдельно отзывать их не нужно.

Ошибки

Код	Когда
401	Ключ неверный, отозван, истёк или его владелец заблокирован. Причина в ответе намеренно не раскрывается; ответ один и тот же во всех этих случаях
403	Ключ не даёт доступа к организации из URL либо в нём нет права, нужного методу; или у владельца ключа нет прав на операцию

Безопасность

• Храните ключ как пароль: в менеджере секретов или переменной окружения, но не в коде, репозитории, чате и тикетах.
• Не передавайте ключ в URL и не пишите его в логи.
• При подозрении на утечку сразу отзовите ключ в кабинете и выпустите новый.
• Выпуск и отзыв ключей записываются в журнал аудита, а события, выполненные по ключу, содержат его идентификатор — так видно, какая интеграция совершила действие.