4. Токен API

Передача токена в заголовках и проверка доступа запросом /os/v1/me.

Каждый запрос должен содержать токен в одном из следующих заголовков:

Authorization: Bearer <токен> — основной способ передачи токена;
x-api-key: <токен> — альтернативный способ, используемый в том числе SDK Anthropic.

Передача токена в строке адреса не поддерживается: такой запрос рассматривается как запрос без токена.

curl https://api.bbx.kz/os/v1/me \
  -H "Authorization: Bearer qos_YOUR_TOKEN"

# The same token in the x-api-key header
curl https://api.bbx.kz/os/v1/me \
  -H "x-api-key: qos_YOUR_TOKEN"

При отсутствии, неверном значении или отзыве токена возвращается ответ 401 с кодом invalid_api_key, при истечении срока действия — 401 с кодом token_expired, при блокировке токена — 403 с кодом token_blocked.

После 30 неудачных попыток авторизации с одного IP-адреса в течение 10 минут запросы с этого адреса отклоняются в течение 15 минут с кодом too_many_auth_failures.

4.1. Сведения о токене

Запрос GET /os/v1/me возвращает сведения о токене и статистику его использования за текущий месяц. Запрос не требует доступа к какому-либо модулю и применяется для проверки работоспособности интеграции.

JSON

{
  "token": {
    "name": "Student services integration",
    "prefix": "qos_Xk2Lp9aQ",
    "modules": ["ALEM", "ACADEMIC", "SCHEDULING"],
    "rpmLimit": 120,
    "expiresAt": "2027-06-30T23:59:59Z"
  },
  "usage": {
    "month": "2026-10",
    "requests": 1842,
    "totalTokens": 512300
  }
}

Поля ответа:

token.name — наименование токена;
token.prefix — начальные символы токена, служащие для его идентификации;
token.modules — коды доступных модулей;
token.rpmLimit — допустимое число запросов в минуту либо null, если ограничение не установлено;
token.expiresAt — дата и время окончания срока действия токена либо null, если срок не ограничен;
usage — число запросов и количество токенов, израсходованных моделями, за текущий месяц.