Гайд · TNWS AI

Как получить access token GigaChat API в 2026 году: OAuth, RqUID и scope

WindowsmacOSLinuxGigaChat#GigaChat API #OAuth #access token

12 сентября 2026 2 мин—

Актуальная авторизация GigaChat API: POST /api/v2/oauth, Basic-ключ, UUID в RqUID, три scope, срок токена 30 минут и безопасное обновление.

Чтобы вызвать GigaChat API, сначала обменяйте Authorization key на короткоживущий access token. По документации, обновлённой 17 июля 2026 года, токен получают POST-запросом к https://ngw.devices.sberbank.ru:9443/api/v2/oauth, передают уникальный UUID4 в RqUID и выбирают scope. Токен действует 30 минут, поэтому выпускать его перед каждым запросом нельзя.

Рабочий пример

RQUID=$(uuidgen)

curl -L -X POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -H 'Accept: application/json' \
+  -H "RqUID: $RQUID" \
+  -H "Authorization: Basic $GIGACHAT_AUTH_KEY" \
+  --data-urlencode 'scope=GIGACHAT_API_PERS'

Проверенные факты

GIGACHAT_API_PERS используется физлицами; для организаций предусмотрены GIGACHAT_API_B2B и GIGACHAT_API_CORP в зависимости от схемы обслуживания.
Успешный ответ содержит access_token и expires_at; ориентируйтесь на expires_at, а не на локальное предположение «прошло примерно полчаса».
Документация допускает до 10 запросов получения токена в секунду, но нормальное приложение кэширует токен и обновляет заранее.
Authorization key — это не access token: первый используется для обмена, второй передаётся как Bearer при обращении к моделям.

Порядок действий

Создайте проект GigaChat API и сохраните Authorization key в менеджере секретов.
Сгенерируйте новый UUID4 для RqUID каждого OAuth-запроса.
Выберите scope, соответствующий типу договора, иначе получите ошибку доступа.
Сохраните token и expires_at в серверном кэше; обновляйте за 60–120 секунд до истечения.
При 401 обновите токен один раз и повторите исходный запрос, защищая операции от дублей.

Как проверить результат

Декодировать или публиковать токен не нужно. Сделайте GET https://api.giga.chat/v1/models с Authorization: Bearer ...: код 200 и массив моделей подтверждают авторизацию. Затем подставьте просроченный токен — обработчик должен получить новый и выполнить только один повтор.

Ограничения

С 17 июля 2026 года целевой URL API — https://api.giga.chat; старый gigachat.devices.sberbank.ru оставлен для ранее подключённых клиентов, но планируется к выводу. Условия сертификатов, доступных scope и подключения проверяйте в кабинете своего проекта.

Чего не делать

Не храните Authorization key в фронтенде.
Не выпускайте новый токен для каждого chat-запроса.
Не повторяйте операцию бесконечно после 401.

Частые вопросы

Сколько живёт access token?

30 минут согласно актуальной документации.

Что передавать в RqUID?

Новый идентификатор UUID4.

Какой scope выбрать физлицу?

GIGACHAT_API_PERS.

Можно ли использовать старый API-адрес?

Для старых подключений он пока доступен, но новые интеграции направляют на api.giga.chat.

Официальный источник

Проверено 12 сентября 2026 года: https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/gigachat-api