Services and Traffic Flow

Procivis One is a multi-service stack. This page explains what each service does, how they communicate, and how authentication works when you first start the stack.

Core and BFF

The two central services are Core and the BFF.

Core is the credential engine at the center of the stack, handling protocols and formats. Most platform operations — including issuing, holding, and verifying credentials, creating and managing keys, certificates and DIDs, and publishing trust lists — route through Core.

Core exposes several API surfaces:

• /api — Management and operator APIs, authenticated via the BFF and STS layer.
• /ssi — Protocol and publication endpoints. Covers OpenID4VCI and OpenID4VP flows, and public-facing publication of DIDs, schemas, trust lists, revocation lists, and related metadata. When you trigger operations through /api, Core handles the appropriate /ssi calls automatically. These endpoints are publicly routable and mostly unauthenticated; certain protocol endpoints require flow-specific authentication.
• /health and /metrics — unauthenticated, for internal use only; not intended for public routing
• /.well-known endpoints — publicly routable and unauthenticated protocol-specific endpoints

BFF (Backend for Frontend) is the orchestration layer for the Desk operator UI, and the home of the Secure Token Service (STS). The STS mediates between your identity provider and Core, exchanging IDP tokens for application tokens that Core accepts. Operator calls routed through the BFF carry session context and user attribution via the subject claim in the token.

Authentication out of the box

When you start the full stack for the first time, authentication is already wired and working for testing and development.

Operator path

The BFF operates exclusively in STS mode. All calls routed through it require authentication with the integrated IDP. This is why the quick start ends with a login step: you authenticated through a Keycloak instance included in the example stack. This bootstrapped Keycloak is enough to start using the platform, and you can perform most operations from inside Procivis One until you are ready to migrate to your own identity provider.

Core, WRPR, and Bridge

These services start in UNSAFE_STATIC mode, one of three supported authentication modes. In this mode, each service accepts the static token defined in your environment variables. These are intentional starter values, appropriate for development and local testing.

Core is also directly accessible at localhost:3000 (or whichever domain you setup in the quick start) using the static taken — for example, via the Swagger UI at localhost:3000/swagger-ui. Calls made this way bypass the BFF entirely and carry no user attribution.

Moving toward production

When you move toward production, you will migrate Core, WRPR, and Bridge from UNSAFE_STATIC to STS mode, and eventually replace the bootstrapped Keycloak with your own IDP.

All service map

The following diagram shows all services that could be included in the full stack. Your deployment may vary, depending on your use case.

Click to expand

Procivis One services

Service	Role
Frontend	The Desk operator UI.
BFF	Orchestration layer for the Desk; houses the STS.
Core	The credential platform.
WRPR	Wallet-Relying Party Registry. Publish national registries of wallet-relying parties and issue Access and Registration Certificates.
Bridge	Enables credential-based authentication via OpenID Connect.

Core, BFF, WRPR, and Bridge each have their own MariaDB database. BFF additionally uses Redis for session management.

Auxiliary services

Service	Role
Traefik	Reverse proxy and single ingress point for operator traffic.
oauth2_proxy	Session authentication at the ingress layer.
Keycloak	Bootstrapped identity provider. Replace with your own IDP for production.

Keycloak uses PostgreSQL.