Configuration Files

This page describes how to load SDK settings. All options ultimately map to DealCloudConfig and the underlying intapp-rest-client RestClient (timeouts, retries, auth, tracing).

Preferred: `DealCloudConfig` with secrets from Azure Key Vault

For production, read credentials from a vault and construct DealCloudConfig in code—nothing sensitive belongs in source control.

Example using Azure Key Vault (opens in a new tab) with DefaultAzureCredential (opens in a new tab) (local dev, managed identity in Azure, etc.). Install Azure SDK packages separately: pip install azure-identity azure-keyvault-secrets.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
 
from dealcloud_sdk import DealCloud, DealCloudConfig, QuerySettings
 
vault_url = "https://your-vault-name.vault.azure.net/"
credential = DefaultAzureCredential()
kv = SecretClient(vault_url=vault_url, credential=credential)
 
# Secret names and mapping are yours to define
site_url = kv.get_secret("DealCloud-SiteUrl").value
client_id = int(kv.get_secret("DealCloud-ClientId").value)
client_secret = kv.get_secret("DealCloud-ClientSecret").value
 
config = DealCloudConfig(
    siteUrl=site_url,
    clientId=client_id,
    clientSecret=client_secret,
    querySettings=QuerySettings(pageSize=1000, cellPaginationLimit=9000, deletePageSize=10000),
)
 
dc = DealCloud.from_config_object(config)

💡

In Azure App Service, Container Apps, AKS, and similar, you can instead use Key Vault references (opens in a new tab) or workload identity so secrets appear as environment variables at runtime—then you still assemble a DealCloudConfig (or use the legacy from_env() path at the end of this page) if that fits your deployment model.

`DealCloudConfig` from a file: `from_config` or `from_config_object`

From a JSON or YAML file on disk (full DealCloudConfig shape):

from dealcloud_sdk import DealCloud
 
dc = DealCloud.from_config("dealcloud_config.json")
# or
dc = DealCloud.from_config("dealcloud_config.yaml")

Parse a file into DealCloudConfig, then pass the object:

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig.from_json_file("dealcloud_config.json")
# or: DealCloudConfig.from_yaml_file("dealcloud_config.yaml")
 
dc = DealCloud.from_config_object(config)

Build DealCloudConfig programmatically (dynamic or test code):

from dealcloud_sdk import DealCloud, DealCloudConfig, QuerySettings, ConcurrencyLimits, ResponseRetrySettings
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    connectorTimeoutSeconds=120,
    querySettings=QuerySettings(
        pageSize=500,
        cellPaginationLimit=5000,
        deletePageSize=5000,
    ),
    concurrencyLimits=ConcurrencyLimits(read=4, delete=2, create=2),
    responseRetrySettings=ResponseRetrySettings(
        tooManyRequests=10,
        internalServerError=3,
        serviceUnavailable=3,
        backoffFactor=2.5,
    ),
)
 
dc = DealCloud.from_config_object(config)

Full configuration file examples

{
  "siteUrl": "yoursite.dealcloud.com",
  "clientId": 12345,
  "clientSecret": "your-client-secret",
  "connectorTimeoutSeconds": 100,
  "querySettings": {
    "pageSize": 1000,
    "cellPaginationLimit": 9000,
    "deletePageSize": 10000
  },
  "concurrencyLimits": {
    "read": 2,
    "delete": 2,
    "create": 2
  },
  "responseRetrySettings": {
    "tooManyRequests": 5,
    "internalServerError": 2,
    "serviceUnavailable": 2,
    "backoffFactor": 2
  },
  "raiseOnRowErrors": false
}

🔐

Secrets: Use a vault or secret store for real clientSecret values. Files in examples use placeholders only.

Legacy entry points (easier migration)

📦

DealCloud.from_yaml(path), DealCloud.from_json(path), and DealCloud.from_env() remain supported so older scripts and minimal configs keep working. New integrations should prefer DealCloudConfig with a vault or full config files as described above.

`from_yaml` and `from_json` (credential-focused files)

Load simple JSON/YAML that primarily holds credentials (optional key path for nested documents). If the file contains a full DealCloudConfig, the SDK may steer you toward from_config() instead.

{
  "siteUrl": "yoursite.dealcloud.com",
  "clientId": 12345,
  "clientSecret": "your-secret"
}

from dealcloud_sdk import DealCloud
 
dc = DealCloud.from_json("credentials.json")

Nested key path

{
  "logging": { "level": "INFO" },
  "dealcloud": {
    "siteUrl": "yoursite.dealcloud.com",
    "clientId": 12345,
    "clientSecret": "your-secret"
  }
}

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

Environment-specific JSON

{
  "production": {
    "siteUrl": "prod.dealcloud.com",
    "clientId": 11111,
    "clientSecret": "${PROD_SECRET}",
    "querySettings": { "pageSize": 1000 }
  },
  "staging": {
    "siteUrl": "staging.dealcloud.com",
    "clientId": 22222,
    "clientSecret": "${STAGING_SECRET}",
    "querySettings": { "pageSize": 500 }
  }
}

import os
 
env = os.getenv("ENVIRONMENT", "staging")
dc = DealCloud.from_json("config.json", env)

`from_env` (environment variables only)

Reads the standard DC_SDK_* (and related) variables—no file. See Authentication — Environment variables for the full list.

from dealcloud_sdk import DealCloud
 
dc = DealCloud.from_env()

💡

Every option in the reference tables below can also be set via environment variables, whether you use from_env() or inject values before building DealCloudConfig elsewhere.

Configuration schema reference

The SDK supports a comprehensive configuration schema compatible with the DealCloud .NET SDK.

Configuration Options

Required Settings

Property	Type	Description
`siteUrl`	`string`	Your DealCloud site URL (without `https://`)
`clientId`	`int`	API Client ID from DealCloud admin
`clientSecret`	`string`	API Client Secret

Connector Settings

Property	Type	Default	Description
`connectorTimeoutSeconds`	`int`	`100`	HTTP request timeout in seconds

Query Settings

Controls pagination and batch sizes:

Property	Type	Default	Description
`pageSize`	`int`	`1000`	Records per page for row operations
`cellPaginationLimit`	`int`	`9000`	Cells per page for cell operations
`deletePageSize`	`int`	`10000`	Records per delete batch

{
  "querySettings": {
    "pageSize": 1000,
    "cellPaginationLimit": 9000,
    "deletePageSize": 10000
  }
}

💡

Larger page sizes can improve performance but increase memory usage. The defaults are optimized for most use cases.

Concurrency Limits

Controls parallel request limits:

Property	Type	Default	Description
`read`	`int`	`2`	Max concurrent read requests
`delete`	`int`	`2`	Max concurrent delete requests
`create`	`int`	`2`	Max concurrent create/update requests

{
  "concurrencyLimits": {
    "read": 2,
    "delete": 2,
    "create": 2
  }
}

⚠️

Higher concurrency may trigger rate limiting. The defaults respect DealCloud's API limits.

Retry Settings

Controls automatic retry behavior for failed requests:

Property	Type	Default	Description
`tooManyRequests`	`int`	`5`	Retries for HTTP 429
`internalServerError`	`int`	`2`	Retries for HTTP 500
`serviceUnavailable`	`int`	`2`	Retries for HTTP 503
`backoffFactor`	`float`	`2`	Exponential backoff multiplier

{
  "responseRetrySettings": {
    "tooManyRequests": 5,
    "internalServerError": 2,
    "serviceUnavailable": 2,
    "backoffFactor": 2
  }
}

The retry delay follows exponential backoff: delay = backoffFactor ^ attempt_number seconds.

Format Compatibility

The SDK auto-detects and supports both configuration formats:

Legacy Format (snake_case)

For backward compatibility with older SDK versions:

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

Modern Format (camelCase)

Compatible with the DealCloud .NET SDK:

{
  "siteUrl": "yoursite.dealcloud.com",
  "clientId": 12345,
  "clientSecret": "your-secret"
}

Validating configuration

The SDK validates configuration when you construct a client:

from dealcloud_sdk import DealCloud
 
try:
    dc = DealCloud.from_config("dealcloud_config.json")
except ValueError as e:
    print(f"Invalid configuration: {e}")

Common issues:

Error	Cause	Solution
`Missing required field: siteUrl`	Credentials missing	Add required fields
`Invalid clientId type`	Wrong data type	Ensure `clientId` is an integer
`File not found`	Config file missing	Check file path
`Invalid JSON/YAML syntax`	Malformed file	Validate file syntax

Migration Guide Authentication