Authentication

The DealCloud SDK uses OAuth2 client credentials for authentication. HTTP calls go through intapp-rest-client (RestClient); advanced options (timeouts, retries, logging) align with that library unless overridden by DealCloudConfig.

This page covers all available authentication methods for the DealCloud SDK.

Quick Start

Use DealCloudConfig (OAuth2 client credentials) and DealCloud.from_config_object():

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-client-secret",
)
dc = DealCloud.from_config_object(config)

Full options (timeouts, retries, query settings) and vault-backed setups are covered in Configuration Files.

⚠️

Security: Never commit credentials to version control. Load secrets from a vault or environment, or use config files that stay out of git.

📦

Legacy shortcut: DealCloud(site_url=..., client_id=..., client_secret=...) still works for small scripts and migration from older samples; prefer DealCloudConfig for anything you maintain long term.

Choose Your Authentication Method

Select based on your deployment environment:

Deployment Type	Recommended Method	Why
Kubernetes / Containers	Environment Variables	Native secret injection, no file mounting
Azure / AWS / GCP	Environment Variables + Secrets Manager	Cloud-native secret rotation
Enterprise / On-Prem	JSON/YAML Config File	Centralized config management, full settings
Local Development	`.env` File	Easy to manage, git-ignored
Multi-Environment	JSON/YAML with Nested Configs	Single file, multiple environments
CI/CD Pipelines	Environment Variables	Injected by pipeline, no file artifacts

💡

Preference: Both JSON/YAML config files and environment variables support all advanced settings. Choose based on your deployment needs - environment variables work great for containers and CI/CD, while config files are ideal for centralized configuration management.

Authentication Methods

Environment Variables

Best for containerized deployments (Kubernetes, Docker, ECS) and CI/CD pipelines.

from dealcloud_sdk import DealCloud
 
# Uses default environment variable names
dc = DealCloud.from_env()

Default environment variable names:

Required Credentials

Variable	Description
`DC_SDK_SITE_URL`	Your DealCloud site URL
`DC_SDK_CLIENT_ID`	API Client ID
`DC_SDK_CLIENT_SECRET`	API Client Secret

Optional Configuration Settings

Variable	Type	Default	Description
`DC_SDK_CONNECTOR_TIMEOUT_SECONDS`	`int`	`100`	HTTP request timeout in seconds
`DC_SDK_QUERY_PAGE_SIZE`	`int`	`1000`	Records per page for row operations
`DC_SDK_QUERY_CELL_PAGINATION_LIMIT`	`int`	`9000`	Cells per page for cell operations
`DC_SDK_QUERY_DELETE_PAGE_SIZE`	`int`	`10000`	Records per delete batch
`DC_SDK_CONCURRENCY_LIMIT_READ`	`int`	`2`	Max concurrent read requests
`DC_SDK_CONCURRENCY_LIMIT_DELETE`	`int`	`2`	Max concurrent delete requests
`DC_SDK_CONCURRENCY_LIMIT_CREATE`	`int`	`2`	Max concurrent create/update requests
`DC_SDK_RETRY_TOO_MANY_REQUESTS`	`int`	`5`	Retries for HTTP 429
`DC_SDK_RETRY_INTERNAL_SERVER_ERROR`	`int`	`2`	Retries for HTTP 500
`DC_SDK_RETRY_SERVICE_UNAVAILABLE`	`int`	`2`	Retries for HTTP 503
`DC_SDK_RETRY_BAD_GATEWAY`	`int`	`2`	Retries for HTTP 502
`DC_SDK_RETRY_GATEWAY_TIMEOUT`	`int`	`2`	Retries for HTTP 504
`DC_SDK_RETRY_BACKOFF_FACTOR`	`float`	`2.0`	Exponential backoff multiplier
`DC_SDK_RETRY_MAX_BACKOFF_SECONDS`	`float`	`300.0`	Maximum wait between retries

Kubernetes Example

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: my-app
          env:
            # Required credentials
            - name: DC_SDK_SITE_URL
              value: "yoursite.dealcloud.com"
            - name: DC_SDK_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: dealcloud-credentials
                  key: client-id
            - name: DC_SDK_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: dealcloud-credentials
                  key: client-secret
            # Optional: Performance tuning
            - name: DC_SDK_CONNECTOR_TIMEOUT_SECONDS
              value: "120"
            - name: DC_SDK_QUERY_PAGE_SIZE
              value: "2000"
            - name: DC_SDK_CONCURRENCY_LIMIT_READ
              value: "4"
            # Optional: Retry configuration
            - name: DC_SDK_RETRY_TOO_MANY_REQUESTS
              value: "10"

Custom Variable Names

dc = DealCloud.from_env(
    site_url_env_name="MY_DC_URL",
    client_id_env_name="MY_DC_CLIENT",
    client_secret_env_name="MY_DC_SECRET"
)

Local Development with .env Files

With python-dotenv (opens in a new tab):

Minimal configuration (credentials only):

# .env file (add to .gitignore!)
DC_SDK_SITE_URL=yoursite.dealcloud.com
DC_SDK_CLIENT_ID=12345
DC_SDK_CLIENT_SECRET=your-secret

Full configuration (all settings):

# .env file (add to .gitignore!)
DC_SDK_SITE_URL=yoursite.dealcloud.com
DC_SDK_CLIENT_ID=12345
DC_SDK_CLIENT_SECRET=your-secret
 
# Optional: Customize timeouts and performance
DC_SDK_CONNECTOR_TIMEOUT_SECONDS=120
DC_SDK_QUERY_PAGE_SIZE=2000
DC_SDK_CONCURRENCY_LIMIT_READ=4
 
# Optional: Customize retry behavior
DC_SDK_RETRY_TOO_MANY_REQUESTS=10
DC_SDK_RETRY_BACKOFF_FACTOR=2.5

from dotenv import load_dotenv
from dealcloud_sdk import DealCloud
 
load_dotenv()  # Load .env file
dc = DealCloud.from_env()  # Automatically uses all configured environment variables

💡

Full Configuration Support: Environment variables now support all configuration options available in JSON/YAML files. You can mix and match - only set the environment variables you want to customize, and defaults will be used for the rest.

JSON Configuration File (Full Settings)

Best for enterprise deployments requiring full configuration control.

{
  "siteUrl": "yoursite.dealcloud.com",
  "clientId": 12345,
  "clientSecret": "your-secret",
  "connectorTimeoutSeconds": 100,
  "querySettings": {
    "pageSize": 1000
  },
  "responseRetrySettings": {
    "tooManyRequests": 5,
    "internalServerError": 2,
    "backoffFactor": 2
  }
}

dc = DealCloud.from_json("config.json")

This format supports all configuration options including timeouts, pagination, and retry settings.

YAML Configuration File

YAML format for human-readable configuration. Preferred for DevOps teams familiar with Kubernetes/Helm.

# config.yaml
siteUrl: yoursite.dealcloud.com
clientId: 12345
clientSecret: your-secret
connectorTimeoutSeconds: 100
querySettings:
  pageSize: 1000
responseRetrySettings:
  tooManyRequests: 5
  internalServerError: 2
  backoffFactor: 2

dc = DealCloud.from_yaml("config.yaml")

💡

YAML support requires the yaml extra:

pip: pip install dealcloud-sdk[yaml]
uv: uv add dealcloud-sdk[yaml]
poetry: poetry add dealcloud-sdk -E yaml

Pydantic Config Object

For programmatic configuration:

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    connectorTimeoutSeconds=120,
    querySettings={
        "pageSize": 500
    }
)
 
dc = DealCloud.from_config_object(config)

For a config file path, use DealCloud.from_config("dealcloud_config.json") instead.

Configuration Formats

The SDK supports two configuration formats and auto-detects which is being used:

Format	Case Style	Full Settings	Recommended For
camelCase	camelCase	✅ Yes	New projects
snake_case	snake_case	❌ Credentials only	Backward compatibility

💡

The camelCase format matches our DealCloud .NET SDK, enabling shared config files across Python and .NET projects.

camelCase Format (Recommended)

{
  "siteUrl": "yoursite.dealcloud.com",
  "clientId": 12345,
  "clientSecret": "your-secret",
  "connectorTimeoutSeconds": 100,
  "querySettings": {
    "pageSize": 1000
  },
  "responseRetrySettings": {
    "tooManyRequests": 5,
    "internalServerError": 2,
    "backoffFactor": 2
  }
}

This format supports all advanced configuration options.

snake_case Format (Backward Compatible)

{
  "site_url": "yoursite.dealcloud.com",
  "client_id": 12345,
  "client_secret": "your-secret"
}

Use this if migrating from an older Python SDK version. Advanced settings require the camelCase format.

Token Management

The SDK automatically handles OAuth2 token management:

Automatic Token Refresh: Tokens are refreshed before expiration
Thread-Safe: Token management is thread-safe for concurrent requests
No Manual Management: You never need to handle tokens directly

from dealcloud_sdk import DealCloud, DealCloudConfig
 
# Tokens are managed automatically
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Make requests without worrying about tokens
data = dc.read_data("Company", output="pandas")  # Token obtained automatically
data2 = dc.read_data("Contact", output="pandas")  # Token reused or refreshed

Multi-Environment Setup

Pattern for managing multiple DealCloud environments:

from dealcloud_sdk import DealCloud
import os
 
def get_client(env: str = "production") -> DealCloud:
    """Get DealCloud client for specified environment."""
    config_map = {
        "production": "config/prod.json",
        "staging": "config/staging.json",
        "development": "config/dev.json"
    }
    
    config_file = config_map.get(env)
    if not config_file:
        raise ValueError(f"Unknown environment: {env}")
    
    return DealCloud.from_json(config_file)
 
# Usage
dc_prod = get_client("production")
dc_staging = get_client("staging")

Security Best Practices

By Deployment Type

Cloud-Native Secrets Management

# AWS - Use Secrets Manager
import boto3
import json
 
def get_dc_client():
    client = boto3.client('secretsmanager')
    secret = json.loads(
        client.get_secret_value(SecretId='dealcloud/prod')['SecretString']
    )
    return DealCloud(
        site_url=secret['siteUrl'],
        client_id=secret['clientId'],
        client_secret=secret['clientSecret']
    )

# Azure - Use Key Vault
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
 
def get_dc_client():
    credential = DefaultAzureCredential()
    kv = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential)
    return DealCloud(
        site_url=kv.get_secret("dc-site-url").value,
        client_id=kv.get_secret("dc-client-id").value,
        client_secret=kv.get_secret("dc-client-secret").value
    )

General Guidelines

Never hardcode credentials in source code
Match auth method to deployment - see table above
Restrict file permissions on config files (chmod 600)
Rotate credentials regularly (quarterly recommended)
Use separate credentials for dev/staging/production
Audit API access using DealCloud's activity logs

Next Steps

Configuration Files - Detailed configuration options
Advanced Configuration - Timeouts, retry, concurrency
Tracing - OpenTelemetry integration

Configuration Files Advanced Configuration