Vehicle Custody

Developer Hub

SDK Usage Policy

The Vehicle Custody SDKs are the official and only supported way to interact with VECU services. This policy exists to protect your integration from unexpected breaking changes.

Why This Matters

Directly calling the underlying APIs — rather than using the SDK — bypasses the stability guarantees that SDK versioning provides. Here's what that means in practice:

  • Underlying API endpoints are internal implementation details, not a public contract. They are subject to change at any time.
  • Endpoints may change in purpose, functionality, or be removed without notice or deprecation period.
  • There is no API versioning guarantee — versioning is managed at the SDK level, through SDK releases.
  • Direct API callers will not receive support when endpoints change. Breakage caused by direct API access is out of scope for VECU support.

Supported Usage

The following are the officially supported ways to interact with VECU services:

  • Use official SDK packages — Install and use the published SDK for your platform (IDV SDK, Wallet SDK, Custody SDK, Verifier SDK)
  • Upgrade SDK versions to access new features and receive fixes
  • Use environment factory methods such as CustodyClient.sandbox() and CustodyClient.production() — the SDK handles all endpoint routing automatically

Unsupported Usage

The following are not supported and may break at any time without notice:

  • Reverse-engineering SDK network calls to build custom HTTP clients
  • Calling internal endpoints directly via fetch, requests, HttpClient, or similar HTTP libraries
  • Relying on observed endpoint paths or response shapes outside the SDK interface

How Versioning Works

The SDK is your versioned interface to VECU services. When we make changes to the underlying API, the SDK is updated to handle those changes internally — you upgrade your SDK package and everything continues to work.

Upgrade your SDK package to access new capabilities. SDK versions follow semantic versioning:

  • Patch releases (1.0.x) — bug fixes, no breaking changes
  • Minor releases (1.x.0) — new features, backward compatible
  • Major releases (x.0.0) — breaking changes, migration guide provided

The SDK handles all API compatibility internally, so you don't have to track internal API changes.

Questions?

If you have questions about SDK usage or need help with your integration, reach out to the VECU team at vecu-dev@coxautoinc.com.