Skip to content
VB-OSVB-OSVB-OS Docs

Connect Evidence Sources to VB-OS

Connectors let VB-OS acquire evidence directly from external systems instead of requiring your application to gather and submit everything.

1. Choose a Provider

Section titled “1. Choose a Provider”

VB-OS supports multiple provider types:

  • Database: PostgreSQL, MySQL, and other SQL databases
  • REST API: any HTTP API that returns JSON
  • Identity Provider: OIDC/SAML-based identity systems
  • Custom: webhook-based integration for any system

2. Create the Connector

Section titled “2. Create the Connector”
from vbos import VBOSClient


client = VBOSClient(api_key="YOUR_API_KEY")


connector = client.connectors.create(
    project_id="PROJECT_ID",
    name="core-banking-balance",
    provider="rest_api",
    config={
        "base_url": "https://banking-api.internal/v1",
        "timeout_ms": 5000,
    },
)

Credentials are encrypted at rest. They never appear in API responses, logs, or error messages.

3. Configure Field Mapping

Section titled “3. Configure Field Mapping”

Map the external system’s response fields to boundary evidence fields:

client.connectors.update(
    project_id="PROJECT_ID",
    connector_id=connector["id"],
    evidence_mappings=[
        {
            "source_path": "balance_cents",
            "evidence_field": "account_balance",
        },
        {
            "source_path": "risk_rating",
            "evidence_field": "risk_score",
        },
    ],
)

Each mapping specifies:

  • source_path: dot-notation path into the external system’s response
  • evidence_field: the boundary evidence field it maps to

4. Use Provenance in Boundaries

Section titled “4. Use Provenance in Boundaries”

Reference the provenance in your boundary:

require_provenance: account_balance: core_banking_system
require_provenance: risk_score: core_banking_system

Now the boundary requires that these fields come from the core banking system connector, not from direct API submission.

5. Test the Connector

Section titled “5. Test the Connector”

Verify the connector is working:

test_result = client.connectors.test(
    project_id="PROJECT_ID",
    connector_id=connector["id"],
)

Security

Section titled “Security”
  • Credentials are encrypted at rest using platform-managed keys
  • Connector configurations are sanitized in all API responses
  • OAuth connectors support token refresh and rotation
  • Webhook-based connectors verify request signatures

Next Steps

Section titled “Next Steps”