REST API Overview
The eduID Wallet Matching Portal exposes its functionality through five distinct API groups spread across three backend services. Every endpoint communicates with JSON request and response bodies and follows standard HTTP status-code semantics: 2xx for success, 4xx for client errors (validation, authentication, not-found), and 5xx for unexpected server-side failures. Understanding the boundary between these API groups is essential for integrating with the portal, debugging issues, and reasoning about the security model.
The three services are:
- Auth Bridge (Java / Spring Boot) -- handles wallet presentation verification, identity reconciliation, and the external third-party API.
- STS (Java / Spring Boot) -- a lightweight OAuth2 / OIDC authorization server that issues tokens consumed by the portal frontend and, optionally, by external clients.
- Portal (Next.js) -- the user-facing web application whose server-side API routes act as a Backend-For-Frontend (BFF), ensuring that no browser-originated request ever reaches Auth Bridge or STS directly.
API Surface Summary
The table below lists every API group, the service that hosts it, the base URL used to reach it, the authentication mechanism it expects, and a short description of its purpose.
| API Group | Service | Base URL | Auth | Description |
|---|---|---|---|---|
| OID4VP Sessions | Auth Bridge | :8090/auth/oid4vp | Internal (service-to-service) | Wallet authentication session lifecycle -- create, poll, and complete OID4VP presentation sessions |
| IDV Reconciliation | Auth Bridge | :8090/auth/oid4vp/sessions/{id}/idv | Internal (service-to-service) | Identity verification during reconciliation -- initiate OIDC-based IDV, handle callbacks, check status |
| External API | Auth Bridge | :8090/api/external/v1/reconciliation | OAuth2 Bearer token | Third-party access to reconciled identity data, auxiliary data storage, and GDPR erasure |
| STS Endpoints | STS | :8080 (or :8092) | OIDC / OAuth2 | Full OAuth2 authorization server -- authorization, token, introspection, revocation, JWKS, and discovery |
| Frontend BFF | Portal | :3000/api | Session Cookie (NextAuth.js) | Browser-to-backend proxy routes that mediate all frontend communication with STS and Auth Bridge |
Service Ports and Environment Configuration
Each service listens on a well-known port. In the default Docker Compose configuration the ports are mapped as follows:
| Service | Container Port | Docker Compose Host Port | Environment Variable |
|---|---|---|---|
| Auth Bridge | 8090 | 8090 | AUTH_BRIDGE_URL |
| STS | 8080 | 8092 | STS_ISSUER_URL, STS_INTERNAL_URL |
| Portal (Next.js) | 3000 | 3000 | NEXTAUTH_URL |
The STS port deserves special attention. Inside the Docker network the STS container listens on its default port 8080, but the docker-compose.yml file maps it to 8092 on the host to avoid conflicts with other services (such as Keycloak) that might also claim port 8080. When configuring environment variables, use the host-mapped port for any URL that the browser or an external client will resolve, and the container port for URLs resolved inside the Docker network:
# Resolved by the browser (host port)
STS_ISSUER_URL=http://localhost:8092
# Resolved inside Docker network (container port)
STS_INTERNAL_URL=http://sts:8080
The AUTH_BRIDGE_URL follows the same pattern. The portal's server-side code uses the internal Docker hostname (http://auth-bridge:8090), while any documentation or tooling running outside Docker should target http://localhost:8090.
Authentication Patterns
The portal uses three distinct authentication patterns, each tailored to the trust relationship between the caller and the service being called.
1. STS Tokens for User-Facing Flows
When a human user authenticates -- whether through institutional federation or wallet presentation -- the STS issues a standard OAuth2 authorization-code-with-PKCE flow. The resulting access_token (a signed JWT) and refresh_token are stored in the NextAuth.js session on the portal backend. The frontend never sees or stores raw tokens; it relies on its HTTP-only session cookie to prove its identity to the BFF layer, which then attaches the appropriate bearer token when proxying requests to Auth Bridge.
Browser --[session cookie]--> Portal BFF --[Bearer access_token]--> Auth Bridge
2. Client Credentials for the External API
Third-party systems that need to query reconciled identity data or store auxiliary information authenticate using the OAuth2 client_credentials grant. They obtain a bearer token from the STS (or a configured external identity provider such as Keycloak) and present it in the Authorization header when calling the External API. The token is validated against the configured JWKS endpoint, and the client's allowed scopes and projected claims are enforced server-side.
External System --[client_credentials grant]--> STS/Keycloak
External System --[Bearer token]--> Auth Bridge External API
3. Session Cookies for the Frontend
The portal frontend communicates exclusively through the BFF routes at /api/*. These routes are protected by the NextAuth.js session middleware, which validates the encrypted HTTP-only cookie attached to every browser request. No token or credential is ever exposed to client-side JavaScript. This design eliminates an entire class of token-theft attacks and keeps the browser's security surface minimal.
Browser --[encrypted cookie]--> Next.js API route --[internal call]--> Auth Bridge / STS
What to Read Next
Each API group has its own dedicated page with full request/response schemas, status codes, error formats, and integration guidance:
- OID4VP Sessions -- create, poll, and complete wallet authentication sessions.
- IDV Reconciliation -- initiate identity verification when the wallet holder is unknown.
- External API -- third-party access to reconciled identities and auxiliary data.
- STS Endpoints -- the OAuth2/OIDC authorization server surface.
- Frontend BFF -- the Next.js proxy routes that tie everything together for the browser.