OAuth 2.0: обзор

OAuth 2.0 позволяет вашему приложению обращаться к API Bito от имени аккаунта клиента. Выданные Bito токены несут контекст аккаунта, поэтому каждый запрос автоматически ограничен данными этого клиента — идентификатор аккаунта передавать не нужно.

TIP

Если вы работаете только с одним аккаунтом — своим, — OAuth не нужен. Отправляйте заголовок api-key, см. Работа с API.

Два способа получить код авторизации

Есть два сценария получения кода авторизации. Оба заканчиваются одним и тем же эндпоинтом обмена и дают одну и ту же пару access_token + refresh_token.

Что вы делаете	Сценарий	Кто начинает
Интеграция для маркетплейса, которую клиенты ставят изнутри Bito	Поток установки (Flow A)	Клиент, в панели Bito
Ваш продукт, где клиент нажимает «Подключить Bito» в вашем интерфейсе	Поток подключения (Flow B)	Ваше приложение
Фоновая задача без участия пользователя для уже установившего вас клиента	Client credentials	Ваш сервер

                    Flow A                          Flow B
              (начинает Bito)                (начинаете вы)

  Клиент нажимает «Установить»        Клиент нажимает «Подключить»
  в Bito                             в вашем приложении
                |                                   |
                v                                   v
  Bito отправляет POST с кодом        Вы перенаправляете на id.bito.uz,
  на ваш redirect_uri                клиент входит, Bito возвращает
                |                    его обратно с ?code=
                |                                   |
                +-----------------+-----------------+
                                  |
                                  v
                     POST /auth/oauth/token
                     (grant_type=authorization_code)
                                  |
                                  v
                   access_token + refresh_token

Права доступа (scopes)

Scope определяет, сколько доступа даёт вам клиент.

Scope	Значение	Описание
Admin	admin	Полный административный доступ ко всем ресурсам
Read	read	Доступ только на чтение
Write	write	Создание и изменение ресурсов
Delete	delete	Удаление ресурсов

Права: настоящий контроль

Scope в токене сам по себе запрос не ограничивает. Каждый запрос к Integration API — с OAuth-токеном или с api-key — проверяется так:

1. required_permissions → granted_permissions. Приложение объявляет права ERP, которыми оно пользуется в Integration API (required_permissions, те же ключи, что у ролей). Клиент видит именно этот список перед установкой, а установка записывает его копию в интеграцию как granted_permissions. Каждый запрос проверяется по этой копии: если права нет, запрос отклоняется. Если позже изменить required_permissions, уже установившего аккаунта это коснётся только после повторной установки. Пустой список — все права.
2. available_scopes. Если у клиента заданы available_scopes, scope, соответствующий действию запроса (read, write или delete; admin покрывает всё), должен быть в этом списке, иначе запрос отклоняется. Если список пуст, эта проверка не выполняется.

Объявляйте самый узкий рабочий список required_permissions — именно по нему клиент понимает, на что соглашается перед установкой.

Эндпоинты

Метод	Путь	Авторизация	Назначение
POST	/auth/oauth/auth	Нет	Client credentials
POST	/auth/oauth/token	Нет	Обмен кода или обновление
POST	/auth/get-one-time-token	Bearer (сессия пользователя)	Одноразовый токен

Хост: https://api.bito.uz на проде, https://api.systematicdev.uz на деве.