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

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

Вернуться к схеме интеграции.

Получите credentials

Запросите у администратора Gigma отдельные client_id, client_secret и audience для нужного Application. Получить эти credentials через публичные методы API нельзя.

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

Проверка Counterparty 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

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

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

Передавайте параметры в теле form-запроса. 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

{
    "active": true,
    "principal_handle": "0f1c1f8e-7a64-4c7a-9c10-1dd25edc54d0",
    "project": { "id": 12 },
    "application": {
        "id": 34,
        "name": "Личный кабинет"
    },
    "scopes": ["chat: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.