API Gateway
Single ingress for all client traffic. Spring Cloud Gateway, routes defined programmatically in
GatewayConfig.java (not application.yml).
Request flow
Auth models by caller
| Caller | Mechanism | Checked where |
|---|---|---|
| Issuer / Admin | JWT bearer token | Gateway (JwtTokenValidationGatewayFilter) |
| Holder / Verifier / Custodian | HttpOnly cookie session | Core Engine (not gateway-inspected) |
| Public endpoints | None | — |
Route groups
| Group | Path prefix | Auth | Backend |
|---|---|---|---|
| Credential verify | /api/v1/credentials/verify, /api/v1/verify/** | Public | Core Engine |
| Credential issuance | /api/v1/credentials/issue, /batch | JWT optional (BYOK signature substitutes) | Core Engine |
| Issuer registration & admin ops | /api/v1/issuer/**, /api/v1/issuers/** | Public (register) / JWT admin (approve, reject, rotate, status, SSO) | Core Engine |
| Holder wallet | /api/v1/holder/** | Cookie session | Core Engine — see Holder Authentication |
| Verifier | /api/v1/verifier/** | Public (auth) / Cookie session (profile) | Core Engine — see Verifier / Employer Identity |
| Custodian | /api/v1/custodian/**, /api/v1/custodians/** | Cookie session / JWT admin | Core Engine |
| Admin login | /api/v1/admin/auth/login | Public (issues token) | Admin Console :8084 |
| Admin (remainder) | /api/v1/admin/** | JWT (ADMIN/OPERATOR/VIEWER) | Admin Console :8084 |
| Admin catalog | /api/v1/admin/catalog/** | JWT | Core Engine — routed before the blanket admin rule |
| Issuer portal | /api/v1/portal/** | JWT (issuer session) | Core Engine |
| Fallback | /api/v1/** | Public / self-validating | Core Engine |
LLM-backed endpoints (credential-insight, support-ask, issuer-kyc-document,
admin/audit-logs/nl-search) carry their own tighter rate limits — see
LLM Integration.
CORS
Dev-server origins allowed by default: issuer-portal (5173), verifier-portal (5174),
admin-console (5175), credential-wallet (5176), custodian-portal (5178). landing (5177)
doesn’t call the API, so it needs no CORS entry. Deployed environments override the allowlist
per-frontend with each ${DOMAIN} subdomain, since every MFE sits behind the nginx reverse proxy
there instead of a raw Vite dev port.
Admin Console integration
| Property | Value |
|---|---|
| Port (REST) | 8084 |
| Schema | console — independent from operational schemas |
| Auth | Admin JWT (ADMIN, OPERATOR, VIEWER) |
| Rate limit | 10 req/min per admin user |
Covers admin user management, system configuration, audit logs (including natural-language
search), live container log tailing, network stats, and system health — all under
/api/v1/admin/**.
Observability
- Every routed verification request triggers a background audit log entry in
core.audit_logs, surfaced to the holder viaGET /api/v1/holder/access-logs. X-Correlation-IDpropagates Gateway → Core Engine → microservices for end-to-end tracing.