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

FreeMaint принимает два механизма аутентификации: JWT (выдаваемые /auth/login, используемые нашими веб- и мобильными приложениями) и ключи API (созданные в /company-settings/api, используемые вашими собственными интеграциями).

JWT (сессии пользователей)

1. POST/аутентификация/вход — Тело: {адрес электронной почты, пароль}. Возвращает {access_token,refresh_token}.
2. Отправьте заголовок Authorization — В каждом запросе: Authorization: Bearer <access_token>.
3. Обновить по истечении срока действия — POST /auth/refresh с Refresh_token, чтобы получить новый access_token. Токены доступа действуют 2 часа.

Ключ API (интеграция с сервером)

1. Откройте /company-settings/api или /profile/api-keys — Администраторы создают ключи в «Настройки компании > API», начиная с тарифа Business. Сотрудник, чья роль имеет разрешение «Создавать личные API-ключи», создаёт собственные ключи в «Профиль > Безопасность > API-ключи». Роль с правом «Управление интеграциями» (например, шаблон «Администратор интеграций») может создавать, отзывать и удалять ключи компании, не будучи администратором; передать ключ другому человеку может только администратор.
2. Нажмите «Новый ключ» — При желании задайте срок действия и уровень доступа (по умолчанию — «Только чтение»). Ключ в исходном виде показывается ОДИН раз — скопируйте его сразу.
3. Используйте это — Отправляйте Authorization: Bearer fmk_<rawKey> в каждом запросе. Формат: начинается с fmk_, за которым следуют 32 шестнадцатеричных символа.

Примечания по безопасности

• Ключи API хранятся в виде хешей SHA-256 — как только вы закроете диалоговое окно раскрытия, необработанное значение будет невозможно восстановить.
• Отзыв ключа немедленно отключает его; строка сохраняется для проверки
• Каждый ключ принадлежит одной компании и даёт доступ только к её данным — запись другой компании просто не находится
• Ключи могут иметь дополнительный атрибут expiresAt для кратковременной интеграции.
• Уровни доступа — потолок поверх разрешений владельца: READ (по умолчанию — только запросы), READ_STOCK (запросы + adjustStock — идеально для киоска выдачи), FULL (любая операция, которую разрешает роль владельца)
• Каждый ключ действует от имени своего владельца: каждый вызов несёт его разрешения и его видимость данных, а всё, что ключ записывает, подписывается его именем. Если владельца деактивируют, ключ отклоняется (401, код API_KEY_OWNER_INACTIVE), пока администратор не передаст его другому сотруднику в «Настройки компании > API», — значение ключа при этом не меняется.

Тестирование интеграции

Отдельной песочницы не существует: ключ API всегда обращается к реальным данным компании, которой он принадлежит. Безопасно протестировать можно двумя способами. (1) Используйте вторую компанию как тестовую — изоляция между компаниями обеспечивается тем же механизмом, что разделяет всех клиентов, поэтому ничто из сделанного там не затронет ваши рабочие данные. Для ключей API нужен тариф Business, поэтому эта компания тоже должна быть на Business: бесплатная компания создать ключ не может. (2) Для работы только на чтение создайте ключ с уровнем доступа READ: он выполняет любые запросы и ни одной мутации, то есть вообще ничего не меняет. Когда дойдёт до записи, ключ READ_STOCK разрешает adjustStock и ничего больше.