introspect

[POST] /oauth/introspect

Introspection проверяет токен и возвращает информацию о том, активен ли он. Этот метод обычно вызывает сервер ресурса, перед тем как принять запрос с access_token.

Access token REGOS — opaque: его содержимое нельзя использовать для локальной проверки подписи или чтения claims. Сервер ресурса получает сведения о доступе из ответа introspection. После active: true он также проверяет ожидаемые iss и aud, срок exp и необходимые scope. Introspection вызывается сервером ресурса с его учётными данными; секрет нельзя размещать в native-приложении.

Запрос отправляется как application/x-www-form-urlencoded. Клиент должен подтвердить себя через HTTP Basic Auth или через поля client_id и client_secret в теле формы. Для новых интеграций предпочтительнее Basic Auth, потому что секрет не смешивается с обычными параметрами запроса.

curl -X POST https://auth.regos.uz/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "your_client_id:your_client_secret" \
  -d "token=opaque_access_token" \
  -d "token_type_hint=access_token"

Параметры формы:

Название	Обязательность	Описание
`token`	Да	Токен, который нужно проверить.
`token_type_hint`	Нет	Подсказка для сервера. Обычно `access_token`.
`client_id`	Да, если не используется Basic Auth	Идентификатор клиента.
`client_secret`	Да, если не используется Basic Auth	Секрет клиента.

Если токен действителен, ответ содержит active: true и публичные сведения, которые помогают ресурсу принять решение о доступе.

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "your_client_id",
  "token_type": "Bearer",
  "exp": 1760000000,
  "iat": 1759999400,
  "sub": "user_identifier",
  "aud": "https://api.example.com",
  "iss": "https://auth.regos.uz"
}

Если токен не найден, истек или был отозван, метод возвращает успешный HTTP-ответ с active: false. Это нормальное поведение: ресурс должен просто отказать в доступе.

Отзыв refresh token и обнаружение его повторного использования отзывают всё семейство, включая выданные в нём access tokens. Завершение устройства или изменение безопасности пользователя также делает соответствующие токены неактивными.

REGOS инвалидирует кэш состояния после отзыва. При сбоях инвалидирования ранее сохранённый положительный ответ может оставаться действительным до 30 секунд. Собственный кэш API добавляет задержку: ограничивайте его срок требованиями к отзыву и всегда значением exp. Ошибка или недоступность introspection не является подтверждением доступа; сервер ресурса не должен разрешать запрос на основании неуспешной проверки.