Configuration

Configure the VECU Custody Python SDK for your application needs.

What This Section Covers

Client initialization options, environment presets, timeout and retry settings, and advanced configuration patterns for both sync and async clients.

SDK-Only Access

To ensure your integration remains stable and supported, always use the official SDKs. The underlying API endpoints are internal implementation details that may change in purpose, functionality, or be removed at any time without notice. Direct API access is not supported. Learn more →

The SDK handles environment routing automatically — use the provided environment methods rather than targeting endpoints directly.

Client Initialization

Environment-Specific Methods

The SDK provides convenient methods for each environment:

from vecu_custody import CustodyClient

# Sandbox environment (for development and testing)
client = CustodyClient.sandbox(token="your-jwt-token")

# Production environment
client = CustodyClient.production(token="your-jwt-token")

Custom Configuration

For additional options (timeout, retries) or local mock server testing:

from vecu_custody import CustodyClient

client = CustodyClient(
    token="your-jwt-token",
    # base_url is for local mock server testing only
    timeout=60,
    max_retries=5
)

Configuration Options

tokenstrrequired

Your JWT token for authentication.

base_urlstr

For local mock server testing only. The SDK automatically targets the correct environment when using .sandbox() or .production(). Do not use this to call API endpoints directly.

timeoutint

Request timeout in seconds. Default: 30.

max_retriesint

Maximum retry attempts for failed requests. Default: 3.

Environment Presets

The SDK provides built-in environment configurations:

Sandbox Environment

client = CustodyClient.sandbox(token="your-jwt-token")
# Uses the sandbox environment

Use sandbox for:

Development and testing
Testing with isolated data
External partner integrations
Certification testing

Production Environment

client = CustodyClient.production(token="your-jwt-token")
# Uses the production environment

Production Access

Production credentials are different from sandbox. Contact your VECU administrator to obtain production JWT tokens.

Timeout Configuration

Configure request timeouts:

client = CustodyClient.sandbox(
    token="your-jwt-token",
    timeout=60  # 60 seconds
)

Retry Configuration

The SDK automatically retries failed requests for transient errors:

client = CustodyClient.sandbox(
    token="your-jwt-token",
    max_retries=5  # Retry up to 5 times
)

Retryable Errors

The SDK automatically retries on:

Connection errors
Timeout errors
HTTP 429 (Rate limited)
HTTP 500, 502, 503, 504 (Server errors)

Exponential Backoff

Retries use exponential backoff with jitter for optimal performance.

Context Manager

Use the client as a context manager for automatic resource cleanup:

from vecu_custody import CustodyClient

with CustodyClient.sandbox(token="your-jwt-token") as client:
    # Client automatically closes when exiting context
    authorization = client.authorizations.create(
        vin="9HGBH41JXMN999999",
        origin="LOC-AUCTION-MANHEIM-ATLANTA",
        destination="LOC-DEALERSHIP-CARMAX-ORLANDO",
        person_identity_key="vecu_gfTRAjYnn_y-8zj-aBc4dEf5",
        authorized_by="system-integration",
        make_model="Honda Accord 2023"
    )

Configuration Patterns

Environment-Based Configuration

import os
from vecu_custody import CustodyClient

def get_client() -> CustodyClient:
    env = os.getenv("APP_ENV", "development")
    token = os.environ["VECU_API_KEY"]

    config = {
        "development": {
            "method": CustodyClient.sandbox,
            "timeout": 60,
            "max_retries": 5,
        },
        "staging": {
            "method": CustodyClient.sandbox,
            "timeout": 30,
            "max_retries": 3,
        },
        "production": {
            "method": CustodyClient.production,
            "timeout": 30,
            "max_retries": 3,
        },
    }

    env_config = config[env]
    method = env_config.pop("method")
    return method(token=token, **env_config)

Singleton Pattern

from vecu_custody import CustodyClient
from functools import lru_cache
import os

@lru_cache(maxsize=1)
def get_custody_client() -> CustodyClient:
    """Return a singleton CustodyClient instance."""
    return CustodyClient.sandbox(token=os.environ["VECU_API_KEY"])

# Usage
client = get_custody_client()

Dependency Injection

from vecu_custody import CustodyClient
from dataclasses import dataclass

@dataclass
class CustodyService:
    client: CustodyClient

    def check_releasability(self, vin: str) -> bool:
        result = self.client.releasability.check_vin(vin=vin)
        return result.is_releasable

# Usage
client = CustodyClient.sandbox(token="your-jwt-token")
service = CustodyService(client=client)

Health Checks

Check if the service is available:

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

# Simple boolean check
if client.health_check():
    print("Service is healthy")
else:
    print("Service is unavailable")

# Detailed health information
health = client.get_health()
print(f"Service: {health.service}")
print(f"Version: {health.version}")
print(f"Status: {health.status}")

Next Steps

Advanced Async Patterns - FastAPI integration, concurrency, and background tasks
Error Handling - Handle errors gracefully
Testing - Test your integration

Vehicle Custody