Карта API

Зачем нужно

Документ задаёт карту API домена identity: группы эндпоинтов, правила контрактов, ошибки, пагинацию, идемпотентность, security headers и связь с OpenAPI.

Детальные поля запросов описываются в профильных документах, но все endpoints должны следовать правилам этой карты.

Базовые правила

• Обычные identity API endpoints начинаются с /api/v2/identity.
• Исключение: OIDC discovery и OAuth endpoints (/.well-known/*, /oauth/*), которые живут на корне домена.
• Ответы используют единый envelope.
• Ошибки используют единый формат.
• Все authenticated endpoints требуют JWT access token.
• Admin endpoints требуют RBAC permission на сервере.
• Изменяющие операции пишут audit, если меняют безопасность, доступ, роли, OAuth clients, plugins или platform settings.
• Все списки поддерживают pagination и фильтры, если могут вырасти.
• Все опасные операции требуют явного confirmation или re-auth.

Response envelope

{
  "data": {},
  "meta": {
    "requestId": "uuid",
    "page": 1,
    "perPage": 25,
    "total": 100,
    "cursor": null
  }
}

Ошибка

{
  "error": {
    "code": "identity.auth.invalid_credentials",
    "message": "Неверные данные входа",
    "details": {}
  },
  "meta": {
    "requestId": "uuid"
  }
}

Сообщение ошибки для пользователя может быть нейтральным. Техническая причина хранится в logs/audit без раскрытия секретов.

Auth API

Метод	Путь	Назначение
POST	/api/v2/identity/auth/register	регистрация
POST	/api/v2/identity/auth/flow/start	старт auth flow
POST	/api/v2/identity/auth/flow/next	следующий шаг auth flow
POST	/api/v2/identity/auth/login	простой вход, если включён как сокращение auth flow
POST	/api/v2/identity/auth/refresh	refresh token rotation
POST	/api/v2/identity/auth/logout	logout текущей сессии
POST	/api/v2/identity/auth/logout-all	logout всех сессий
POST	/api/v2/identity/auth/password/reset/start	старт reset password
POST	/api/v2/identity/auth/password/reset/confirm	подтверждение reset password
POST	/api/v2/identity/auth/contacts/verify/start	отправить код подтверждения контакта
POST	/api/v2/identity/auth/contacts/verify/confirm	подтвердить контакт

Profile and users API

Метод	Путь	Назначение
GET	/api/v2/identity/me	текущий пользователь
PATCH	/api/v2/identity/me/profile	обновить профиль
GET	/api/v2/identity/me/sessions	мои сессии
DELETE	/api/v2/identity/me/sessions/{id}	отозвать сессию
GET	/api/v2/identity/admin/users	список пользователей
POST	/api/v2/identity/admin/users	создать пользователя
GET	/api/v2/identity/admin/users/{id}	карточка пользователя
PATCH	/api/v2/identity/admin/users/{id}	изменить пользователя
POST	/api/v2/identity/admin/users/{id}/block	заблокировать
POST	/api/v2/identity/admin/users/{id}/unblock	разблокировать

RBAC API

Метод	Путь	Назначение
GET	/api/v2/identity/admin/roles	список ролей
POST	/api/v2/identity/admin/roles	создать кастомную роль
PATCH	/api/v2/identity/admin/roles/{id}	изменить роль
GET	/api/v2/identity/admin/permissions	список permissions
POST	/api/v2/identity/admin/users/{id}/roles	назначить роль
DELETE	/api/v2/identity/admin/users/{id}/roles/{assignmentId}	снять роль
GET	/api/v2/identity/me/permissions	effective permissions текущего пользователя

Family API

Метод	Путь	Назначение
GET	/api/v2/identity/families	семьи пользователя
POST	/api/v2/identity/families	создать семью
GET	/api/v2/identity/families/{id}	детали семьи
PATCH	/api/v2/identity/families/{id}	изменить базовые настройки семьи
POST	/api/v2/identity/families/{id}/student-profiles	добавить student_profile ребёнка
PATCH	/api/v2/identity/families/{id}/student-profiles/{studentProfileId}	изменить семейно-управляемые поля ребёнка
POST	/api/v2/identity/families/{id}/student-profiles/{studentProfileId}/link-user	привязать или создать user ребёнка
POST	/api/v2/identity/families/{id}/invitations	пригласить взрослого
POST	/api/v2/identity/family-invitation-tokens/{token}/accept	принять family invitation
POST	/api/v2/identity/families/{id}/delegated-sessions	начать delegated session
DELETE	/api/v2/identity/families/{id}/delegated-sessions/{sessionId}	завершить delegated session
POST	/api/v2/identity/families/{id}/student-profiles/{studentProfileId}/device-authorizations	создать запрос входа ребёнка на устройстве
POST	/api/v2/identity/families/{id}/device-authorizations/{authorizationId}/approve	взрослый подтверждает запрос
POST	/api/v2/identity/families/{id}/device-authorizations/{authorizationId}/complete	устройство ребёнка завершает вход
POST	/api/v2/identity/families/{id}/device-authorizations/{authorizationId}/revoke	отозвать запрос

Self-service удаление семьи, выход взрослого, удаление adult member, перенос и отвязка ребёнка не входят в пользовательский MVP Family API. Эти операции выполняются вручную администраторами и должны проектироваться отдельно.

Organizations API

Метод	Путь	Назначение
GET	/api/v2/identity/organization-references/search	поиск справочных и уже созданных организаций
POST	/api/v2/identity/admin/organization-references	создать справочную организацию
PATCH	/api/v2/identity/admin/organization-references/{id}	изменить справочную организацию
GET	/api/v2/identity/organizations	организации пользователя
POST	/api/v2/identity/organizations	создать организацию
GET	/api/v2/identity/organizations/{id}	детали
PATCH	/api/v2/identity/organizations/{id}	изменить
DELETE	/api/v2/identity/organizations/{id}	архивировать, не hard delete
POST	/api/v2/identity/organizations/{id}/membership-requests	подать заявку на вступление
GET	/api/v2/identity/organizations/{id}/membership-requests	список заявок на вступление
POST	/api/v2/identity/organizations/{id}/membership-requests/{requestId}/approve	подтвердить заявку
POST	/api/v2/identity/organizations/{id}/membership-requests/{requestId}/reject	отклонить заявку
POST	/api/v2/identity/organizations/{id}/teams	создать команду
POST	/api/v2/identity/organizations/{id}/invitations	приглашение
GET	/api/v2/identity/organizations/{id}/invitations	приглашения организации
POST	/api/v2/identity/organization-invitation-tokens/{token}/accept	принять приглашение по token
POST	/api/v2/identity/organization-invitation-tokens/{token}/reject	отказаться от приглашения по token
POST	/api/v2/identity/organizations/{id}/invitations/{invitationId}/revoke	отозвать приглашение
POST	/api/v2/identity/organizations/{id}/ownership-claims	подать заявку на владение
GET	/api/v2/identity/admin/organization-ownership-claims	список заявок на владение
POST	/api/v2/identity/admin/organization-ownership-claims/{id}/approve	одобрить заявку на владение
POST	/api/v2/identity/admin/organization-ownership-claims/{id}/reject	отклонить заявку на владение
POST	/api/v2/identity/admin/organization-ownership-claims/{id}/request-more-info	запросить данные
POST	/api/v2/identity/organizations/{id}/ownership-transfers	создать передачу владения
POST	/api/v2/identity/organization-ownership-transfers/{token}/accept	принять передачу владения
POST	/api/v2/identity/organizations/{id}/ownership-transfers/{transferId}/cancel	отменить передачу
GET	/api/v2/identity/organizations/{id}/students	ученики организации
POST	/api/v2/identity/organizations/{id}/students	создать ученика организации
PATCH	/api/v2/identity/organizations/{id}/students/{studentId}	изменить ученика организации
DELETE	/api/v2/identity/organizations/{id}/students/{studentId}	архивировать ученика организации
GET	/api/v2/identity/admin/organizations	admin list организаций
GET	/api/v2/identity/admin/organizations/{id}	admin карточка организации
POST	/api/v2/identity/admin/organization-merges	создать merge plan
POST	/api/v2/identity/admin/organization-merges/{id}/confirm	подтвердить merge plan после impact preview
POST	/api/v2/identity/admin/organization-merges/{id}/complete	выполнить merge

OAuth/OIDC API

Метод	Путь	Назначение
GET	/.well-known/openid-configuration	OIDC discovery
GET	/.well-known/jwks.json	public keys
GET	/oauth/authorize	authorization endpoint
POST	/oauth/token	token endpoint
GET	/oauth/userinfo	userinfo
POST	/oauth/introspect	token introspection
POST	/oauth/revoke	token revocation
GET	/oauth/end_session	RP-initiated logout
GET	/api/v2/identity/admin/oauth/clients	список clients
POST	/api/v2/identity/admin/oauth/clients	создать client
PATCH	/api/v2/identity/admin/oauth/clients/{id}	изменить client

Notifications, events, audit

Метод	Путь	Назначение
GET	/api/v2/platform/notifications	in-app уведомления
GET	/api/v2/platform/notifications/unread-count	счётчик непрочитанных
PATCH	/api/v2/platform/notifications/{id}/read	отметить прочитанным
POST	/api/v2/platform/notifications/read-all	отметить все прочитанными
DELETE	/api/v2/platform/notifications/{id}	удалить уведомление
DELETE	/api/v2/platform/notifications/read	удалить все прочитанные
GET	/api/v2/platform/notifications/settings	настройки пользователя
PATCH	/api/v2/platform/notifications/settings/{ruleId}	изменить настройку правила
GET	/api/v2/platform/admin/notifications/rules	правила уведомлений
POST	/api/v2/platform/admin/notifications/rules	создать правило уведомлений
PATCH	/api/v2/platform/admin/notifications/rules/{id}	изменить правило уведомлений
DELETE	/api/v2/platform/admin/notifications/rules/{id}	удалить правило уведомлений
GET	/api/v2/platform/admin/notifications/templates	шаблоны уведомлений
PATCH	/api/v2/platform/admin/notifications/templates/{id}	изменить шаблон уведомлений
GET	/api/v2/identity/admin/audit-logs	audit logs
GET	/api/v2/identity/admin/events	event logs

Platform, plugins, transports

Эти endpoints platform-owned и временно обслуживаются identity-api как bootstrap host. Canonical owner — platform по ADR-035.

Метод	Путь	Назначение
GET	/api/v2/platform/settings/public	публичные настройки
GET	/api/v2/platform/navigation	меню текущего пользователя
GET	/api/v2/platform/pages	страницы текущего пользователя
GET	/api/v2/platform/admin/settings	settings
PATCH	/api/v2/platform/admin/settings	изменить settings
GET	/api/v2/platform/admin/plugins	список plugins
POST	/api/v2/platform/admin/plugins/install	установить plugin
POST	/api/v2/platform/admin/plugins/{id}/enable	включить
POST	/api/v2/platform/admin/plugins/{id}/disable	выключить
DELETE	/api/v2/platform/admin/plugins/{id}	удалить
GET	/api/v2/platform/admin/transports	transports

Security requirements

• x-request-id возвращается в каждом ответе.
• Cookies, если используются, должны быть HttpOnly, Secure, SameSite.
• OAuth endpoints имеют отдельные rate limits.
• Auth endpoints имеют rate limits по IP, identifier и user.
• Admin endpoints требуют CSRF protection, если используются cookie sessions.
• File upload endpoints проверяют размер, MIME type, extension и storage policy.

Идемпотентность

Идемпотентность нужна для:

• отправки verification code;
• принятия invitation;
• создания OAuth client;
• установки plugin;
• изменения role assignment;
• повторных callback от provider.

Для повторяемых команд используется Idempotency-Key, если операция может быть вызвана клиентом повторно из-за сетевой ошибки.

Готовность

• все endpoints имеют owner document;
• OpenAPI генерируется из контроллеров;
• ошибки имеют коды;
• audit покрывает security/business changes;
• rate limits заданы для auth, OAuth, invitations, plugins и admin actions;
• API можно реализовать без неописанных групп endpoints.