Identity Internal API — реестр методов и общие правила области

Реестр internal-методов identity (контекст identity, сервис Pin.Identity.Api, area internal) — machine-to-machine поверхность для gateway и других сервисов: авторизация (check-permission) и интроспекция эффективных прав. Область не обслуживает браузер/человека: только межсервисный вызов внутри периметра. Дома полей — в ../../domain/; соседние реестры для человеческих акторов — public/investor (../README.md), admin (../admin/) и company-user (../company-user/).

Metadata

Поле	Значение
Сервис/контекст	identity
API area	internal (m2m внутри периметра)
Тип документа	api (реестр области, не единичная операция)
Статус	draft
Owner	PIN Platform Core
Область действия	enforcement авторизации (allow/deny по permission + scope); public/admin/company-user — отдельные реестры (../README.md, ../admin/, ../company-user/)
Assumptions	enforcement-контексты (crm, chessboard, catalog, news, gateway) не дублируют ролевую модель, а зовут этот endpoint или держат реплику-кэш с инвалидацией по топику pin.identity.access.v1

Реестр методов

Route-префикс области — /internal/v1/.

Метод	Route	Feature group	Актор	Документ
POST	/internal/v1/authorize/check-permission	authorization	m2m audience pin.identity.internal	check-permission.md

Batch-вариант принимает до 50 проверок за вызов (канбан, списки). Каноническая формула эффективных прав — effectivePermissions(user, resource) из role.md; та же логика применяется при авторизации всех операций identity.

Модель актора и доступ

Проверка	Значение
Actor type	ExternalSystem — сервис/gateway внутри периметра
Auth	m2m токен с audience pin.identity.internal; вне периметра endpoint недоступен (маршрут /internal/* не публикуется наружу gateway-ом)
Проверяемый субъект	UserId из тела запроса — не актор вызова (сервис спрашивает про чужого пользователя)
Записи о вызывающем	нет; identity лишь отвечает allow/deny + причину

Кросс-сервисный контракт

Что identity предоставляет вызывающим:

• Синхронный ответ allow/deny по каждой проверке с машинной причиной (PermissionDenyReason) и первым покрывшим назначением; батч до 50 проверок за вызов, порядок и корреляция — по CheckId.
• Deny by default для неизвестных прав/пользователей (forward-compatible: новый PermissionCode — не ошибка, а PermissionUnknown); добавление полей ресурса — additive.
• Событие инвалидации кэшей UserAccessChangedKafkaEvent (топик pin.identity.access.v1, ключ = UserId) при любом изменении эффективных прав пользователя (назначение/отзыв роли, смена scope, статуса).

Что identity ожидает от вызывающих (enforcement-контексты crm, chessboard, catalog, news, gateway):

• Не дублировать ролевую модель: либо звать check-permission на каждую защищаемую операцию, либо держать локальную реплику-кэш и инвалидировать её по pin.identity.access.v1; не удерживать закэшированный ответ дольше согласованного окна (ориентир — TTL кэша прав 5 мин).
• Fail-closed при недоступности identity: deny + 503 своей операции; не кэшировать аварийный deny дольше 5 с.
• Резолвить принадлежность ресурса иерархии scope (project → group → organization) на своей стороне (владелец данных) и передавать согласованные ресурс-координаты; record-level (владелец/группа записи) enforce-ит сам вызывающий — identity отвечает лишь на уровне permission + scope.

Окно eventual-consistency: отзыв прав вступает в силу после доставки pin.identity.access.v1 и инвалидации кэша; при пропущенной инвалидации остаточное окно ограничено сверху TTL. Возможно кратковременное «ложное allow» на уже отозванное право (≤ TTL) — критичные операции должны это учитывать.

Коды ошибок

Результат проверки прав возвращается в теле ответа (allow/deny), а не HTTP-кодом. Отдельные HTTP-ошибки — только про сбой самого вызова.

Код	HTTP	Условие	Retry
ValidationError	400	Пустой/битый UserId/ресурс-координаты; > 50 проверок в batch	no retry
UNAUTHORIZED	401	Нет/просрочен m2m токен или неверный audience	no retry

Отсутствие права — это IsAllowed = false в теле (200), не 403. Наблюдаемость и SLO авторизации — по ../README.md и ../../use-cases/UC-IDN-008-internal-permission-check.md.

Связанные документы

• Дома полей: ../../domain/role.md (формула effectivePermissions, INV-R8), ../../domain/permission.md (каталог прав).
• Публичный аналог интроспекции (self/чужой с permission) — ../company-user/get-user-effective-permissions.md.
• Use case: ../../use-cases/UC-IDN-008-internal-permission-check.md.
• Решения: ADR-0053 (admin/internal-разделение), ADR-0056 (simplicity-first, кэш прав).
• Соседние реестры: ../README.md (public/investor), ../admin/, ../company-user/.