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 cryptographic and credential engine at the center of the stack. Most platform operations — including issuing, holding, and verifying credentials, managing keys and DIDs, signing certificates, 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-facing endpoints for wallets and verifiers (to retrieve revocation lists); publicly routable, with authentication requirements that vary by flow
• /health and /metrics — unauthenticated, for internal use only; not intended for public routing
• Well-known endpoints — publicly routable and unauthenticated

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 that Procivis ships as part of the 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 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.

Full service map

The following diagram shows all services included in the full stack quick start. WRPR and Bridge are optional — whether you need them depends on your use case.

Click to expand

Service	Role
Traefik	Reverse proxy and single ingress point for operator traffic.
oauth2_proxy	Session authentication at the ingress layer.
Frontend	The Desk operator UI.
BFF	Orchestration layer for the Desk; houses the STS.
Keycloak	Bootstrapped identity provider. Replace with your own IDP for production.
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.

Each service has its own database. Keycloak uses PostgreSQL; all other services use MariaDB.