VB-OS Connector Authentication Patterns

Credential-Based Authentication

The most common pattern. Store encrypted credentials that the connector uses to query the provider:

from vbos import VBOSClient

client = VBOSClient(api_key="YOUR_API_KEY")

connector = client.connectors.create(
    project_id="PROJECT_ID",
    provider="postgresql",
    name="Production Database",
    credentials={
        "connection_string": "postgresql://user:pass@host:5432/db"
    },
)

Credential field names vary by provider: common fields include api_key, connection_string, personal_access_token, and private_key.

All credentials are encrypted at rest using AES encryption. They are never returned in API responses after creation.

OAuth 2.0 Authorization

For providers that support OAuth, the platform manages the full authorization code flow:

1. Initiate: call the authorize endpoint to get an authorization URL
2. Consent: the user authorizes access in the provider’s UI
3. Callback: the platform receives the authorization code and exchanges it for tokens
4. Managed: the platform stores tokens encrypted and handles automatic refresh

OAuth grants track the provider account ID, scopes, and a generation counter for re-authorization.

OAuth Status

Status	Description
NOT_APPLICABLE	Provider does not use OAuth
AUTHORIZATION_REQUIRED	OAuth flow has not been completed
AUTHORIZED	OAuth tokens are valid and active

Webhook Secrets

Connectors that receive inbound webhooks store a separate webhook secret for signature verification. The secret is encrypted at rest, independent of the connector’s primary credentials.

Testing Connections

After configuring authentication, test the connection:

result = client.connectors.test(
    project_id="PROJECT_ID",
    connector_id="CONNECTOR_ID",
)
print(result["success"])  # True or False

Next Steps

• Connectors Overview: how connectors work
• Evidence Mapping: mapping source data to boundary fields