Connections

Connections are secure credential stores for external services. They abstract away authentication complexity and enable your actions and automations to interact with third-party APIs securely.

Concept

A connection combines:

• Provider — Service type (e.g., shopify, salesforce, postgresql)
• Credentials — Encrypted secrets (API keys, OAuth tokens, passwords)
• Config — Non-secret settings (host, database, options)
• Status — Health state (active, error, pending, expired)

Key Features

Connection Types

OAuth Connections

For services like Salesforce, HubSpot, and Shopify that use OAuth2:

1. User initiates OAuth flow
2. Redirected to provider for authorization
3. Provider returns authorization code
4. VirtuousAI exchanges code for tokens
5. Tokens stored encrypted

OAuth connections automatically refresh tokens before expiry.

API Key Connections

For services that use static API keys:

{
  "name": "Production Database",
  "provider": "postgresql",
  "config": {
    "host": "db.example.com",
    "port": 5432,
    "database": "production",
    "ssl": true
  },
  "credentials": {
    "username": "app_user",
    "password": "secure_password"
  }
}

{
  "name": "Stripe API",
  "provider": "rest",
  "config": {
    "baseUrl": "https://api.stripe.com/v1",
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "credentials": {
    "apiKey": "sk_live_..."
  }
}

{
  "name": "Snowflake DW",
  "provider": "snowflake",
  "config": {
    "account": "xy12345.us-east-1",
    "warehouse": "COMPUTE_WH",
    "database": "ANALYTICS",
    "schema": "PUBLIC"
  },
  "credentials": {
    "username": "ETL_USER",
    "password": "...",
    "role": "ETL_ROLE"
  }
}

Supported Providers

Connection Lifecycle

Connection Resolution

Actions and automations can reference connections flexibly:

Examples

Reference a specific connection:

{
  "actionTemplate": "sync-salesforce-leads",
  "connectionRef": { "id": "conn_sf_production" }
}

Use the default Salesforce connection:

{
  "actionTemplate": "sync-salesforce-leads",
  "connectionRef": { "provider": "salesforce" }
}

LLM-friendly slug reference:

{
  "actionTemplate": "extract-orders",
  "connectionRef": { "slug": "shopify" }
}

Security Model

Envelope Encryption

1. Data Encryption Key (DEK) — Unique per connection, encrypts credentials
2. Key Encryption Key (KEK) — AWS KMS key, encrypts DEKs
3. Credentials never stored in plaintext
4. Decryption only at runtime, in-memory

Access Control

• Connections are org-scoped
• Users need appropriate permissions to view/use
• Credentials are never exposed via API (only connection metadata)

Best Practices

1. Use descriptive names — Include environment (prod/staging) and purpose
2. Test before use — Always verify connections work before using in automations
3. Set defaults — Configure a default connection per provider for convenience
4. Rotate credentials — Update API keys periodically for security
5. Monitor status — Set up alerts for connection failures

OpenAPI Reference

For detailed endpoint schemas and response formats: