Справочник запросов

Здесь запросы, которые нужны сервису после входа: узнать, кто вошёл, и завершить сессию. Они одинаковы независимо от того, как получен токен.

Весь поток на одной карте

Если вы попали сюда первым, вот порядок целиком — по ссылкам полные параметры и примеры:

Экран согласия — GET https://id.invoicebox.ru/oauth/authorize, пользователь разрешает доступ, вы получаете code.
Обмен кода на токен — POST /v3/security/oauth/token, grant_type=authorization_code; в ответе access_token, expires_in, refresh_token.
Профиль пользователя — GET /v3/security/api/auth/auth (ниже на этой странице): кто вошёл и какие права выданы.
Обновление токена — когда expires_in истёк.
Отзыв доступа и завершение сессии (ниже) — когда доступ больше не нужен.

Адреса не храните в коде: их сообщают метаданные сервера. Параметры и ответы называются как в стандарте, поэтому подходит любая готовая библиотека OAuth.

Важно

Это OAuth 2.1, а не OpenID Connect. id_token мы не выдаём, документа /.well-known/openid-configuration у нас нет (ни на api.invoicebox.ru, ни на id.invoicebox.ru), метаданные публикуются по RFC 8414.

Токен считайте непрозрачным. Он может выглядеть как JWT, но JWKS мы не публикуем и формат не обещаем: разбирать и проверять подпись локально нельзя — сегодня получится, а после смены формата перестанет. Кто вошёл и какие права — узнавайте запросом профиля ниже.

Профиль пользователя

метод: GET
ресурс: /v3/security/api/auth/auth
заголовок: Authorization: Bearer <токен>

Параметр строки запроса	Что делает
`withPermissions`	`true` — в ответе появится массив `permissions` с правами пользователя внутри организаций. Без параметра массива нет: он стоит отдельного обращения к правам, и платить за него каждой проверкой сессии незачем

{
  "data": {
    "userId": "01771533-8e75-3234-8e3d-9213ae2d7c52",
    "profile": {
      "firstName": "Пётр",
      "lastName": "Смирнов",
      "email": "buh@example.invbox.ru"
    }
  }
}

Поле ответа	Что означает
`userId`	идентификатор пользователя; `null` — токен не принят
`profile`	имя, фамилия, электронная почта
`userIdentifier`	чем пользователь идентифицируется при входе: сама строка входа (телефон или почта) и признак подтверждения
`applicationId`	приложение, которому выдан токен — сверяйте со своим
`scopes`	права, которые пользователь действительно разрешил: именно этот список, а не тот, что вы просили в `scope`
`permissions`	только с `withPermissions=true`: права внутри организаций

Важно

Код 200 не означает успешную авторизацию. Ответ с userId: null приходит и тогда, когда токен не передан или не распознан. Признак рабочего токена — непустой userId.

Этим же запросом удобно проверять, жива ли сессия, перед показом страниц пользователя.

Завершение сессии

метод: DELETE
ресурс: /v3/security/api/auth/logout
заголовок: Authorization: Bearer <токен>

Запрос завершает сессию на стороне Инвойсбокс. Свои куки сервис удаляет сам — если оставить их, человек останется «войденным» в интерфейсе с уже недействительным токеном.

Этот запрос завершает сессию, но не отзывает выданный токен. Чтобы приложение перестало иметь доступ совсем, нужен отзыв доступа — или отзыв со стороны пользователя в личном кабинете.

Справочник запросов

Весь поток на одной карте

Профиль пользователя

Завершение сессии

Читайте также