API лавлах¶

Backend-ийн бүх HTTP гадаргуу нэг хүснэгтэд. Бизнес endpoint-ууд /api/v1/* угтвартай; OIDC provider ба дэд бүтцийн endpoint-ууд үндэс дээр сууна.

Браузер эдгээр рүү ШУУД ханддаггүй

Frontend нь BFF загвартай — браузер зөвхөн ижил-origin /api/* Next.js route руу хандаж, тэр нь server талаас backend руу проксилно. Токен client JS-д хэзээ ч хүрэхгүй. Доорх замууд нь backend-ийн замууд.

Swagger: GET /swagger/doc.json (production-д bearer token шаардана).

Дэд бүтэц¶

Метод	Зам	Хандалт
`GET`	`/health`	нээлттэй
`GET`	`/ready`	нээлттэй
`GET`	`/metrics`	production-д `OBSERVABILITY_TOKEN` (эс бөгөөс 404)
`GET`	`/swagger/doc.json`	мөн адил

OIDC provider¶

OAUTH_ISSUER + SSO_STATE_KEY тохируулагдсан үед идэвхжинэ. Замууд нь OIDC стандартаар тогтоогдсон.

Метод	Зам
`GET`	`/.well-known/openid-configuration`
`GET`	`/.well-known/jwks.json`
`GET`	`/oauth2/auth`
`POST`	`/oauth2/token`
`POST`	`/oauth2/introspect`
`POST`	`/oauth2/revoke`
`GET`	`/oauth2/sessions/logout`
`GET` `POST`	`/userinfo`

Login/consent урсгалын дотоод API: /api/v1/provider/login · /consent · /login/accept · /login/reject · /consent/accept · /consent/reject · /logout/accept.

Нэвтрэлт — `/api/v1/auth`¶

Метод	Зам	Хязгаар
`POST`	`/eid/start`	auth (5/мин)
`POST`	`/eid/start-id`	auth
`POST`	`/eid/poll`	poll (1/сек, burst 30)
`POST`	`/google`	auth
`DELETE`	`/google/link`	нэвтэрсэн
`POST`	`/refresh` · `/logout`	auth
`POST`	`/initiate`	auth (мобайл)
`GET`	`/status/{sid}`	poll (мобайл)

Супер админ: /api/v1/auth/superadmin/mfa · /onboard/{google,eid/start,eid/start-id,eid/poll,email/send,email/verify,totp/init,totp/verify}.

Gerege SSO (RP тал): /api/v1/sso/start · /callback · /native · /logout.

Хэрэглэгч ба байгууллага¶

Метод	Зам	Юу
`GET`	`/api/v1/users/me`	Өөрийн профайл
`GET`	`/api/v1/users/me/eid/summary` · `/certificates` · `/devices` · `/activity`	eID PKI профайл
`GET` `POST` `DELETE`	`/api/v1/users/me/eid/organizations…`	Холбоотой байгууллага
`GET` `POST` `DELETE`	`/api/v1/users/me/eid/organizations/{regNo}/signers…`	Гарын үсэг зурагчид
`POST` `GET`	`/api/v1/org`	Байгууллага үүсгэх / миний байгууллагууд
`GET`	`/api/v1/org/lookup/{regNo}`	Улсын бүртгэлээс лавлах
`GET` `POST` `PUT` `DELETE`	`/api/v1/org/{id}/members…`	Гишүүд ба эрх
`GET`	`/api/v1/core/users` · `/organizations`	Админы хайлт (`users.manage`)

eID Service Proxy¶

Метод	Зам	Олголт
`GET`	`/api/v1/eid/summary` · `/certificates` · `/devices` · `/activity`	`svc:eid-proxy`
`GET`	`/api/v1/eid-org/organizations` · `/organizations/{regNo}/signers`	`svc:eid-org-proxy`
`*`	`/rp/sign/*`	`svc:eid-sign`

Иргэний үйлчилгээ — `/api/v1/gov`¶

Иргэний үйлчилгээ хуудсанд бүтнээр жагсаав. Нийтийн каталог: /api/v1/catalog/services · /services/{id} · /life-events.

Регистр ба Relay¶

Регистр ба Relay хуудсанд бүтнээр жагсаав (/api/v1/registry/*, /api/v1/relay/*).

Gateway ба апп бүртгэл¶

Метод	Зам	Эрх
`GET`	`/api/v1/gateway/overview` · `/logs`	`gateway.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/gateway/services…`	`gateway.manage`
`GET` `POST`	`/api/v1/applications`	`gateway.manage`
`GET` `PUT` `DELETE`	`/api/v1/applications/{id}`	`gateway.manage`
`POST`	`/api/v1/applications/{id}/rotate-secret`	`gateway.manage`
`PUT`	`/api/v1/applications/{id}/secret` · `/services`	`gateway.manage`

Гарын үсэг, асет, файл¶

Метод	Зам
`POST`	`/api/v1/sign/initiate` · `/init`
`GET`	`/api/v1/sign/status/{sid}` · `/{id}` · `/{id}/download`
`GET` `PUT` `DELETE`	`/api/v1/me/signature`
`PUT`	`/api/v1/me/latin-name` · `/org-name-latin/{regNo}`
`GET` `PUT` `DELETE`	`/api/v1/me/orgstamp/{regNo}`
`GET` `POST` `DELETE`	`/api/v1/gspace` · `/upload` · `/download`
`GET` `POST` `DELETE`	`/api/v1/integrations…`

Дэлгэрэнгүй: Баримт, гарын үсэг, файл.

AI¶

Метод	Зам	Хязгаар
`POST`	`/api/v1/ai/chat` · `/stt` · `/tts` · `/translate`	20/мин, burst 10
`POST`	`/api/v1/public/ai/chat` · `/chat/stream`	6/мин, burst 3
`POST`	`/api/v1/public/ai/tts`	20/мин, burst 8

Дэлгэрэнгүй: AI pipeline.

Админ, RBAC, аудит¶

Метод	Зам	Эрх
`GET`	`/api/v1/rbac/me`	нэвтэрсэн
`GET` `POST` `PUT` `DELETE`	`/api/v1/rbac/roles…` · `/permissions`	`roles.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/admin/users…`	`users.manage`
`GET` `PUT`	`/api/v1/admin/ai/prompts…`	`settings.manage`
`POST`	`/api/v1/admin/ai/knowledge/reindex`	`settings.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/superadmin/…`	superadmin
`GET`	`/api/v1/audit` · `/audit/verify`	admin
`POST`	`/api/v1/security/events`	нэвтэрсэн
`GET`	`/api/v1/security/events`	admin
`GET` `PUT`	`/api/v1/site/appearance`	нээлттэй / `settings.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/themes…`	нээлттэй (`/active`) / admin

Дэлгэрэнгүй: Админ, RBAC, аудит.

Алдааны загвар¶

Handler-ууд func(w, r) error хэлбэртэй бөгөөд v1.Wrap-аар ороогдоно. Usecase давхарга apperror.* буцааж, HTTP статус руу төвлөрсөн байдлаар хөрвүүлэгддэг. Дотоод шалтгааныг apperror.InternalCause-аар боож өгдөг тул сангийн алдаа клиент рүү хэзээ ч задардаггүй.