token

[POST] /oauth/token

Метод /oauth/token выдает или обновляет токены. Запрос всегда отправляется как application/x-www-form-urlencoded; JSON для этого метода не используется.

Обмен authorization code на токены

Этот запрос выполняется после возврата пользователя с /oauth/authorize. Передайте одноразовый код, тот же redirect_uri, ваш client_id и code_verifier, если использовался PKCE.

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=one_time_code" \
  -d "redirect_uri=https%3A%2F%2Fyour.app%2Fcallback" \
  -d "client_id=your_client_id" \
  -d "code_verifier=your_code_verifier"

Confidential-клиент также передает client_secret. Публичный клиент не должен иметь секрет в браузере или мобильном приложении.

Успешный ответ:

{
  "access_token": "opaque_access_token",
  "token_type": "Bearer",
  "id_token": "eyJ...id_token",
  "expires_in": 600,
  "refresh_token": "opaque_refresh_token",
  "scope": "openid profile email"
}

Если в ответе есть id_token, приложение должно проверить его подпись и стандартные поля, а затем может читать публичные данные пользователя из payload. Подробное описание состава id_token, включая поля gender и birthdate, вынесено на отдельную страницу id_token. Эти два поля появляются при scope profile: gender возвращается как male или female, а birthdate возвращается в формате YYYY-MM-DD.

Не предполагаете срок жизни токена заранее. Всегда используйте expires_in, который пришел в ответе.

Обновление access token

Метод также поддерживает Device Authorization Flow: grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code и client_id. Перед этим приложение получает коды через /oauth/device_authorization. Пока пользователь не подтвердил вход, ответ authorization_pending с HTTP 400 является ожидаемым; при slow_down увеличьте интервал опроса на 5 секунд. Подробный сценарий, QR и обработка остальных ошибок описаны в разделе «Вход по QR-коду — Device Authorization Flow».

Когда access_token истек, обновите его через refresh_token.

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=opaque_refresh_token" \
  -d "client_id=your_client_id"

Если клиент confidential, добавьте client_secret. После успешного ответа сохраните новые значения токенов. Старый refresh token становится недействительным. Его повторное использование отзывает всю соответствующую цепочку refresh tokens, включая последний выданный токен.

Получение токена приложения

Для серверной интеграции без пользователя используйте client_credentials.

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Ответ содержит access_token, token_type, expires_in и scope. В этом сценарии не выдаются id_token и refresh_token.

Обмен embed token

grant_type=embed_token используется только для встроенных интеграций REGOS. Применяйте его, если REGOS отдельно выдал вам такой сценарий. Обмен выполняется на backend-стороне интеграции; подробный процесс с подключением JavaScript SDK и iframe описан на отдельной странице Embed Token.

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=embed_token" \
  -d "embed_token=one_time_embed_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Успешный ответ содержит delegated access_token, который действует ограниченное время и используется только в рамках согласованного сценария.

Сроки действия и безопасное обновление

Срок access token определяется настройками клиента. Если клиент наследует серверное значение, действует настройка сервера. Число 600 в примере не является универсальным сроком: приложение всегда использует полученный expires_in. Access token имеет формат opaque; сервер ресурса получает exp и состояние доступа через introspection.

Refresh token выдаётся только при разрешённом для клиента refresh_token grant и включённой выдаче refresh tokens. У него два ограничения: абсолютный срок от первоначальной выдачи и срок неактивности (idle). Настройка клиента имеет приоритет; значение 0 означает наследование серверной настройки. Стандартные серверные значения по умолчанию — семь дней для абсолютного срока и сутки для неактивности; в конкретной интеграции они могут быть другими. Обновление продлевает idle-срок, но никогда не сдвигает абсолютный срок цепочки. Изменение абсолютной настройки применяется к новым цепочкам; уже выданная цепочка сохраняет первоначальный предел.

Каждый успешный refresh возвращает новый refresh token. Сохраняйте его вместе с новым access token как одну операцию в защищённом хранилище. Для одной цепочки выполняйте только один refresh одновременно, в том числе между процессами или вкладками. Повторное использование старого токена считается replay — возможным повтором украденных учётных данных — и отзывает всю цепочку. Если ответ потерян в сети, повторять запрос со старым refresh token небезопасно: потребуется новый вход. При invalid_grant удалите локальную пару токенов и начните авторизацию заново.

Смена или сброс пароля, блокировка аккаунта, изменение телефона, email, LDAP-привязки или ролей завершают доступ по существующим сессиям. Пользователь может просмотреть устройства и завершить выбранную сессию или другие сессии в разделе безопасности профиля. Такой выход прекращает обновление токенов для соответствующих сессий.

Политика отзыва opaque access tokens — проверка через introspection: после отзыва семейства его access tokens возвращают active: false. Учитывайте кэш проверки состояния: при сбоях его обновления задержка на стороне REGOS может достигать 30 секунд, а собственный кэш API добавляет задержку. Короткий TTL не заменяет эту проверку.

Все ответы /oauth/token, включая ошибки, содержат:

Cache-Control: no-store
Pragma: no-cache

Механизм обнаружения replay соответствует подходу RFC 9700, раздел 4.14.