Gigma

Проверка Bearer через introspect

Используйте introspect, когда Bearer клиента пришёл вашему backend из другой доверенной системы и нужно проверить, действует ли он для нужного приложения.

Для обычного входа через ваш backend этот запрос не нужен: backend сам получил Bearer от Gigma и может использовать его напрямую.

Как проходит проверка

  1. Получите отдельные client_id, client_secret и audience.
  2. Передайте Bearer и audience в form-теле запроса.
  3. Проверьте поле active.
  4. При active: true свяжите principal_handle с локальным пользователем.
  5. При active: false не выдавайте доступ и запросите новый вход.

Получите credentials

Запросите у администратора Gigma credentials для нужного Application:

  • client_id;
  • client_secret;
  • audience.

Получить их через публичные методы API нельзя.

Сохраните client_secret сразу после выдачи: повторно он не показывается. Храните secret только на backend. Если значение потеряно или скомпрометировано, запросите ротацию.

Проверьте Bearer клиента

Метод
POST
URL
https://api.gigma.ru/api/counterparty/auth/introspect
Авторизация
Basic client credentials
Headers
Authorization: Basic {base64(client_id:client_secret)}; Content-Type: application/x-www-form-urlencoded
Успешный ответ
200

Передайте client_id и client_secret через Basic Auth, а Bearer клиента и audience — в form-теле.

Параметры запроса

  • token (string, обязательно) — Bearer целиком, включая разделитель |.
  • audience (string, обязательно, до 64 символов) — значение, выданное вместе с credentials.

Query-параметры не поддерживаются.

Пример запроса

POST /api/counterparty/auth/introspect HTTP/1.1
Host: api.gigma.ru
Authorization: Basic <base64(client_id:client_secret)>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=12%7CplainSanctumToken&audience=project-backend

Ответ

Для действующего Bearer API вернёт HTTP 200 и active: true.

{
    "active": true,
    "principal_handle": "0f1c1f8e-7a64-4c7a-9c10-1dd25edc54d0",
    "project": { "id": 12 },
    "application": {
        "id": 34,
        "name": "Личный кабинет"
    },
    "scopes": ["counterparty:access"],
    "expires_at": "2026-07-31T03:00:00+00:00"
}
Описание полей ответа
  • active — результат проверки Bearer.
  • principal_handle — стабильный UUID клиента для связи с пользователем вашей системы.
  • project.id — идентификатор проекта Gigma.
  • application.id — идентификатор приложения, выпустившего Bearer.
  • application.name — название приложения.
  • scopes — разрешения backend-клиента.
  • expires_at — время окончания Bearer или null.

Неизвестный, отозванный, просроченный или выпущенный другим приложением Bearer возвращается как неактивный:

{
    "active": false
}

active: false — штатный результат проверки, а не ошибка авторизации backend-клиента.

Ошибки

  • 401 — проверьте client_id, client_secret и состояние backend-клиента.
  • 403 Forbidden. — проверьте audience.
  • 415 Unsupported Media Type. — отправьте application/x-www-form-urlencoded, а не JSON.
  • 422 — передайте token и audience в теле запроса.
  • 429 Too Many Attempts. — дождитесь окончания Retry-After.

Готово: backend получил проверенный идентификатор клиента и знает, действует ли Bearer.

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

  • При active: true дополнительно проверьте ожидаемые project.id, application.id и нужный scope.
  • Используйте principal_handle как стабильную связь с локальным пользователем, а не как публичный идентификатор.
  • Не считайте действующий Bearer доказательством оплаты. Заказ или подписку проверяйте отдельным запросом.
  • При active: false удалите локальную сессию или предложите пользователю войти заново.
  • Не логируйте token, client_secret и заголовок Authorization.

Что дальше