Skip to main content

Integration Patterns

This page explains common integration patterns to help you choose the right approach for your deployment.

Procivis One Desk authentication​

This workflow shows how authenticated users interact with platform services through the web application (Desk).

Authentication and authorization checks​

  • At the gateway: If no valid session cookie is present, the gateway redirects the user to the IAM provider to authenticate and obtain a new token
  • At the BFF: The BFF validates the authorization token and checks the user's permissions before routing requests or exchanging tokens
  • At the Core (and other services in STS mode): The Core validates the application token and enforces both permissions and tenant context. It verifies the requested resources belong to the tenant specified in the token and that the user has the necessary permissions within that tenant.

Technical user authentication​

Services that interact with Core programmatically can authenticate as technical users rather than relying solely on end user tokens. This is recommended for STS mode deployments and full-feature integrations, and applies to first-party services such as BFF, OpenID Bridge, and WRPR as well as any custom services you integrate.

For a full explanation of the technical user model, delegation, and setup instructions, see Technical Users and Delegation.

API clients integrating with BFF​

An API client can integrate with the BFF. In this case, the IAM token is used with the BFF and the BFF makes calls to the Core and Bridge with app tokens. For configuring your IAM to produce authorization tokens the BFF can validate, see IAM token structure.

API clients integrating with Core​

You can also integrate directly with the Core. There are three primary pathways:

  1. Disable STS authentication and implement alternative security controls.

Security Warning

Disabling STS authentication removes the Core's built-in authorization checks, tenant separation, and request attribution. This configuration should only be used when:

  • You understand the associated risks
  • Authentication and authorization are enforced by infrastructure components
  • The network perimeter is tightly controlled and monitored
  • You have implemented compensating security controls

In UNSAFE_NONE mode the Core uses no authentication.

In UNSAFE_STATIC mode the Core enforces no tenant separation and does not log user attribution.

Most deployments should not use these configurations.

  1. Use the /sts endpoint but bypass all other BFF endpoints. In this case follow the technical user authentication workflow. You will setup the BFF service but disable the /api endpoints, only calling for token exchange.

  1. Create the STS token using your own service. In this case you will setup your client to produce tokens the Core can validate. Use the STS token structure for guidance.