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

Адрес авторизации

Пользователя отправляют на https://id.invoicebox.ru/ с параметрами в строке запроса.

Параметр	Что означает
`applicationId` *	идентификатор приложения, выданный службой поддержки
`redirectUri` *	адрес возврата; должен совпадать с зарегистрированным
`state` *	случайная строка; вернётся без изменений, по ней сверяется подлинность возврата
`codeChallenge` *	SHA-256 от `codeVerifier` в base64url
`codeChallengeMethod` *	`S256`

Пример:

https://id.invoicebox.ru/?applicationId=my-service&redirectUri=https%3A%2F%2Fmy-service.ru%2Fauth%2Fcallback%2F&state=8f2c…&codeChallenge=k7Yb…&codeChallengeMethod=S256

После входа пользователь возвращается на redirectUri с параметрами code и state.

Обмен кода на токен

метод: POST
ресурс: /v3/security/api/auth/token
тело запроса — объект ниже
вызывается с сервера: токен не должен попадать в браузер

Свойство	Тип	Описание
`applicationId` *	string	идентификатор приложения
`redirectUri` *	string	тот же адрес, что в запросе авторизации
`code` *	string	код из параметров возврата
`codeVerifier` *	string	исходная строка, от которой считался `codeChallenge`
`clientSecret`	string	только если для приложения выпущен секрет; публичным клиентам не нужен

POST /v3/security/api/auth/token
Content-Type: application/json
Accept: application/json

{
  "applicationId": "my-service",
  "redirectUri": "https://my-service.ru/auth/callback/",
  "code": "e3b0c44298fc1c14",
  "codeVerifier": "s9Zx1kQd…"
}

Ответ:

{
  "data": {
    "accessToken": "b37c4c689295904ed21eee5d9a48d42e"
  }
}

Токен может прийти строкой или вложенным объектом — в реализациях Инвойсбокса разбор устроен терпимо: берётся data.accessToken, а если там объект, то accessToken внутри него. Код обмена одноразовый: повторный запрос с тем же code завершится ошибкой.

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

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

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

Важно

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

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

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

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

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