Аутентифікація

Кожен запит до API авторизується ключем компанії у заголовку Authorization:

Authorization: Bearer samo_live_XXXXXXXXXXXXXXXXXXXXXXXX

Ключ представляє одну компанію. Усе, що ви створюєте цим ключем, належить їй, і бачити ви можете лише її заявки — навіть якщо користувач, який випустив ключ, має доступ і до інших компаній.

Випуск і відкликання

Ключі створює власник компанії в кабінеті: Налаштування → API.

Повний ключ показується один раз — одразу після створення. Далі в списку видно лише префікс, за яким ключ можна впізнати.
Ключів може бути кілька: зручно мати окремий для кожної інтеграції, щоб відкликати їх незалежно.
Відкликаний ключ перестає працювати негайно: подальші запити отримають 401 unauthorized.

Зберігайте ключ так само, як пароль до бази: у змінних оточення або сховищі секретів, ніколи — у репозиторії, у браузері чи в мобільному застосунку. Ключ дає право створювати й видаляти заявки компанії.

Області доступу (scopes)

При створенні ключа обираються області. Це принцип найменших привілеїв: інтеграції, яка лише читає біржу, не потрібне право видаляти ваші заявки.

Область	Що відкриває
`reference:read`	Довідники, пошук населених пунктів, картки компаній та відгуки
`proposals:read`	Пошук по біржі, картка заявки, список власних заявок
`proposals:write`	Створення, редагування, підняття, архівація, відновлення й видалення власних заявок
`employees:read`	Перелік працівників компанії та кількість заявок на кожному
`employees:write`	Увімкнення/вимкнення працівника та зміна його ролі

Області employees:* не видаються за замовчуванням — їх треба явно відмітити при створенні ключа. Ключі, випущені раніше, цих прав не мають: щоб керувати працівниками через API, створіть новий ключ.

Якщо ключу бракує потрібної області, запит завершиться 403 forbidden з поясненням у полі message.

Обмеження за IP

Для ключа можна задати перелік дозволених IP-адрес. Тоді запит із будь-якої іншої адреси відхиляється з 403 forbidden, навіть якщо ключ правильний. Це корисно, коли інтеграція працює з відомого статичного сервера.

Порожній перелік означає «будь-яка адреса».

Що відбувається при зміні тарифу

Доступ до API прив'язаний до тарифу компанії:

при переході на тариф без API ключі перестають авторизуватися, а активні вебхуки компанії вимикаються;
при поверненні на PREMIUM ключі й вебхуки знову працюють — перевипускати нічого не потрібно.

Зміна набирає чинності майже миттєво: кеш прав скидається подією, а не за таймером.

Типові помилки

Симптом	Причина
`401 unauthorized` на першому ж запиті	немає заголовка, забуте слово `Bearer`, обрізаний ключ
`401` після тривалої роботи	ключ відкликано, або тариф компанії більше не містить API
`403 forbidden` на конкретному ендпоінті	ключу не вистачає області доступу
`403 forbidden` на всіх ендпоінтах	запит іде з IP, якого немає в переліку дозволених
`404 not_found` на чужій заявці	заявка належить іншій компанії — API навмисно не розрізняє «немає» і «не ваша»