Custody Permits

Create and manage custody permits (authorizations) for vehicle custody transfers.

Overview

Custody permits authorize specific parties to take custody of vehicles. Each authorization specifies:

• VIN: The vehicle being authorized
• Route: Origin and destination locations (OD pair)
• Person Identity: Who can take custody (from VECU IDV SDK)
• Transport Order: Optional external shipment/order reference
• Validity Period: When the authorization is valid

Methods

CreateAuthorizationAsync()

Create a new custody authorization for a vehicle.

CreateAuthorizationRequest Properties

Returns: AuthorizationResponse with authorization details and status

Exceptions:

• ValidationException - Invalid request parameters (400, 422)
• InvalidOriginAddressException - Origin address rejected by the geocoder (400, ErrorCode=INVALID_ORIGIN_ADDRESS)
• AuthException - Authentication failure (401)
• DuplicateAuthorizationException - Authorization already exists for (VIN, canonicalized origin) (409). Per ADR-042 the disclosure guard is same_client only — cross-tenant collisions return the conflict but omit ExistingAuthorization and the Location header. ExistingAuthorization is nullable — see Error Handling.
• VehicleNotReleasableException - Vehicle cannot be released due to business rules (409)
• RateLimitException - Rate limit exceeded (429)
• PoolCapacityExceededException - Authorization pool at capacity for this VIN under the effective uniqueness scope (429, ErrorCode=POOL_CAPACITY_EXCEEDED)
• DriverLimitExceededException - Multi-driver POST exceeded per-client cap (429, ErrorCode=DRIVER_LIMIT_EXCEEDED). Body carries AttemptedCount + MaxAllowed. NO state changes applied (atomic pre-write rejection).
• MultiDriverModeRequiredException - Caller's client is in single_driver mode but AuthorizedDrivers was supplied (400, ErrorCode=MULTI_DRIVER_MODE_REQUIRED). Subclass of InvalidConfigurationException — catch the parent class to handle the whole config-error family.
• PoolFanOutException - Multi-driver POST pool fan-out failed and was rolled back (503, ErrorCode=POOL_FANOUT_FAILURE). Caller can retry the entire POST. Body carries SucceededDriverCount, RolledBackEntries, and RollbackFailures (composite IDs left orphaned at auth-pool — ops attention required).
• GeocodingServiceUnavailableException - Upstream geocoder unavailable; SDK has exhausted its retry budget (503, ErrorCode=GEOCODING_SERVICE_UNAVAILABLE)
• NetworkException - Network or server errors (5xx)

Example:

using CoxAuto.Vecu.CustodySdk.Client;
using CoxAuto.Vecu.CustodySdk.Models.Requests;
using CoxAuto.Vecu.CustodySdk.Exceptions;

public class AuthorizationService
{
    private readonly ICustodyServiceClient _client;

    public AuthorizationService(ICustodyServiceClient client)
    {
        _client = client;
    }

    public async Task<string> CreateAuthorizationAsync()
    {
        var request = new CreateAuthorizationRequest
        {
            Vin = "1HGBH41JXMN109186",
            Origin = "1 Auction Blvd, Bordentown, NJ 08505",
            Destination = "200 Motor Ave, Columbus, OH 43230",
            PersonIdentityKey = "DL-293-847-561",
            MakeModel = "Honda Accord",
            AuthorizedBy = "CENTRAL_DISPATCH",
            TransportOrderId = "TRO-2024-00472",
            ValidUntil = DateTimeOffset.UtcNow.AddHours(48),
            Role = AuthorizationRole.DRIVER
        };

        try
        {
            var response = await _client.CreateAuthorizationAsync(request);

            Console.WriteLine($"Authorization created: {response.AuthorizationId}");
            Console.WriteLine($"Status: {response.Status}");
            Console.WriteLine($"Created at: {response.CreatedAt}");
            Console.WriteLine($"Expires at: {response.ExpiresAt}");
            Console.WriteLine($"Effective scope: {response.UniquenessScope}");
            Console.WriteLine($"Origin (formatted): {response.OriginFormattedAddress}");
            Console.WriteLine($"Origin geohash: {response.OriginGeohash}");
            Console.WriteLine($"Location header: {response.LocationUri}");

            return response.AuthorizationId;
        }
        catch (DuplicateAuthorizationException ex)
        {
            // ExistingAuthorization is nullable as of v3.2.0 — gate on the
            // null check ALONE. Per ADR-040 §7.1, do NOT infer
            // disclosure-guard denial from a null value (it can also be a
            // transient enrichment failure).
            if (ex.ExistingAuthorization is not null)
            {
                Console.WriteLine($"Existing authorization: {ex.ExistingAuthorization.AuthorizationId}");
            }
            else
            {
                Console.WriteLine($"Conflict on VIN/origin; existing record not surfaced. EffectiveScope={ex.EffectiveScope}");
            }
            throw;
        }
        catch (VehicleNotReleasableException ex)
        {
            Console.WriteLine($"Vehicle not releasable: {ex.Message}");
            throw;
        }
    }
}

GetAuthorizationAsync()

Retrieve detailed information about an authorization by ID.

Returns: AuthorizationDetails with full authorization information

Exceptions:

• ArgumentException - Authorization ID is null or whitespace
• AuthException - Authentication failure (401)
• AuthorizationNotFoundException - Authorization not found (404)
• NetworkException - Network or server errors (5xx)

Example:

using CoxAuto.Vecu.CustodySdk.Exceptions;

public async Task CheckAuthorizationStatus(string authorizationId)
{
    try
    {
        var details = await _client.GetAuthorizationAsync(authorizationId);

        Console.WriteLine($"Authorization: {details.AuthorizationId}");
        Console.WriteLine($"VIN: {details.Vin}");
        Console.WriteLine($"Status: {details.Status}");
        Console.WriteLine($"Origin: {details.Origin}");
        Console.WriteLine($"Destination: {details.Destination}");
        Console.WriteLine($"Role: {details.Role}");
        Console.WriteLine($"Expires at: {details.ExpiresAt}");

        if (details.CancelledAt != null)
        {
            Console.WriteLine($"Cancelled at: {details.CancelledAt}");
            Console.WriteLine($"Cancelled by: {details.CancelledBy}");
            Console.WriteLine($"Reason: {details.CancellationReason}");
        }
    }
    catch (AuthorizationNotFoundException ex)
    {
        Console.WriteLine($"Authorization not found: {ex.Message}");
    }
}

CancelAuthorizationAsync()

Cancel an existing authorization.

CancelAuthorizationRequest Properties

Returns: CancelAuthorizationResponse with cancellation details

Exceptions:

• ArgumentException - Authorization ID is null or whitespace
• ArgumentNullException - Request is null
• AuthException - Authentication failure (401)
• AuthorizationNotFoundException - Authorization not found (404)
• ValidationException - Authorization cannot be cancelled (422)
• NetworkException - Network or server errors (5xx)

Example:

using CoxAuto.Vecu.CustodySdk.Models.Requests;

public async Task CancelAuthorization(string authorizationId)
{
    var request = new CancelAuthorizationRequest
    {
        CancellationReason = "Driver reassigned to different route due to scheduling conflict"
    };

    try
    {
        var response = await _client.CancelAuthorizationAsync(
            authorizationId,
            request);

        Console.WriteLine($"Authorization cancelled: {response.AuthorizationId}");
        Console.WriteLine($"VIN: {response.Vin}");
        Console.WriteLine($"Cancelled at: {response.CancelledAt}");
        Console.WriteLine($"Cancelled by: {response.CancelledBy}");
        Console.WriteLine($"Status: {response.Status}");
        Console.WriteLine($"Reason: {response.CancellationReason}");
    }
    catch (ValidationException ex)
    {
        Console.WriteLine($"Cannot cancel: {ex.Message}");
        // Authorization might already be cancelled, expired, or in use
    }
}

WaitForAuthorizationAsync()

Wait for an authorization to reach a terminal status by polling.

WaitOptions Properties

Returns: AuthorizationDetails when terminal status or custom condition is reached

Terminal Statuses: RELEASED, CANCELLED, EXPIRED, REVOKED

Exceptions:

• ArgumentException - Authorization ID is null or whitespace
• AuthException - Authentication failure (401)
• AuthorizationNotFoundException - Authorization not found (404)
• TimeoutException - Wait timeout exceeded before reaching terminal status
• OperationCanceledException - Operation cancelled via cancellation token
• NetworkException - Network or server errors (5xx)

Example:

using CoxAuto.Vecu.CustodySdk.Client;

public async Task WaitForAuthorization(string authorizationId)
{
    try
    {
        // Wait with default options (5s interval, 5min timeout)
        var details = await _client.WaitForAuthorizationAsync(authorizationId);

        Console.WriteLine($"Authorization reached terminal status: {details.Status}");
        Console.WriteLine($"Expires at: {details.ExpiresAt}");
    }
    catch (TimeoutException)
    {
        Console.WriteLine("Authorization did not reach terminal status within timeout");
    }
}

public async Task WaitWithCustomOptions(string authorizationId)
{
    // Custom wait options
    var options = new WaitOptions
    {
        PollingIntervalSeconds = 10,  // Check every 10 seconds
        TimeoutSeconds = 600,          // Wait up to 10 minutes
        CustomPredicate = auth => auth.Status == AuthorizationStatus.RELEASED
    };

    var cts = new CancellationTokenSource(TimeSpan.FromMinutes(10));

    try
    {
        var details = await _client.WaitForAuthorizationAsync(
            authorizationId,
            options,
            cts.Token);

        Console.WriteLine($"Authorization released: {details.AuthorizationId}");
    }
    catch (TimeoutException)
    {
        Console.WriteLine("Authorization was not released within timeout");
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("Wait operation was cancelled");
    }
}

UpdateAuthorizationDriversAsync()

Add or remove drivers on a multi-driver authorization (ADR-042 §Decision §6). Available only when the authorization was created under multi_driver mode and the calling client owns the authorization. ETag-guarded for optimistic concurrency, idempotent on add/remove operations.

UpdateDriversRequest Properties

Returns: UpdateDriversResponse with the new Version and the post-PATCH AuthorizedDrivers list.

Exceptions:

• MultiDriverModeRequiredException - 400, the authorization was created under single_driver mode (subclass of InvalidConfigurationException).
• NotAuthorizationOwnerException - 403, caller's client_id does not match the authorization's client_id.
• EmptyDriverListException - 400, net effect of the PATCH would leave zero drivers. NO state changes.
• AuthorizationAlreadyAssignedException - 409, authorization is already ASSIGNED — driver-list modifications no longer permitted.
• StaleETagException - 412, version mismatch. Refetch via GetAuthorizationAsync and retry.
• DriverLimitExceededException - 429, proposed list (after applying add/remove) exceeds per-client cap. NO state changes.
• AuthException - 401, invalid or missing JWT.
• NetworkException - 5xx network or server errors.

Example:

using CoxAuto.Vecu.CustodySdk.Models.Requests;
using CoxAuto.Vecu.CustodySdk.Models;
using CoxAuto.Vecu.CustodySdk.Exceptions;

public async Task UpdateDriversExample(string authorizationId, int currentVersion)
{
    var request = new UpdateDriversRequest
    {
        Version = currentVersion,  // ETag from prior fetch
        Add = new List<AuthorizedDriver>
        {
            new()
            {
                PersonIdentityKey = "vecu_dAvEpKxYz1234567",
                Name = "Dave Driver",
            },
        },
        Remove = new List<string> { "vecu_gfTRAjYnn_y-8zj-aBc4dEf5" },  // Alice's personIdentityKey
        ActorIdentifier = "ops-user-42@client.example.com",
    };

    try
    {
        var response = await _client.UpdateAuthorizationDriversAsync(
            authorizationId, request);

        Console.WriteLine($"New version: {response.Version}");
        Console.WriteLine($"Drivers now: {response.AuthorizedDrivers.Count}");
    }
    catch (StaleETagException ex)
    {
        // Concurrent PATCH bumped the version — refetch and retry
        var fresh = await _client.GetAuthorizationAsync(authorizationId);
        Console.WriteLine($"Stale version; current is {fresh.Version}");
    }
    catch (MultiDriverModeRequiredException)
    {
        Console.WriteLine("Authorization was not created under multi_driver mode");
    }
    catch (EmptyDriverListException)
    {
        Console.WriteLine("PATCH would leave no drivers");
    }
    catch (AuthorizationAlreadyAssignedException)
    {
        Console.WriteLine("Cannot modify drivers after AssignAuthorizationToDriverAsync");
    }
}

AssignAuthorizationToDriverAsync()

Lock the authorization to a single chosen driver (ADR-042 §Decision §7). Transitions the authorization to ASSIGNED, cancels non-assigned pool entries, and revokes credentials issued for non-assigned drivers. Sync-blocking: by the time the call returns, all non-assigned credentials are revoked at the credential service.

AssignAuthorizationRequest Properties

Returns: AssignAuthorizationResponse with AssignedDriverPik, new Version, RevokedCredentialIds (credentials revoked as part of the assign — empty pre-acceptance), and DriverAuthorizationMode.

Exceptions:

• DriverNotOnListException - 400, requested PersonIdentityKey is not on the authorization's AuthorizedDrivers list. Use UpdateAuthorizationDriversAsync first to add.
• NotAuthorizationOwnerException - 403, caller does not own the authorization.
• AuthorizationAlreadyAssignedToDifferentDriverException - 409, the authorization is already ASSIGNED to a different driver. Cancel-and-recreate is the only path to change the assigned driver.
• AuthorizationNotAssignableException - 409, the authorization is in a terminal status (RELEASED, EXPIRED, REVOKED, CANCELLED).
• StaleETagException - 412, version mismatch.
• AssignPartialFailureException - 503 ASSIGN_PARTIAL_FAILURE. The authorization IS assigned; credential revocation completed only partially. Safe to retry with the bumped version (revocation is idempotent on the credential-service side). Body carries RevokedCredentialIds (succeeded) and FailedRevocations (each with CredentialId + Reason).

Idempotency: assigning the already-assigned driver to an already-ASSIGNED authorization returns 200 with the existing state and a fresh ETag.

Example:

using CoxAuto.Vecu.CustodySdk.Models.Requests;
using CoxAuto.Vecu.CustodySdk.Exceptions;

public async Task AssignDriver(string authorizationId, int currentVersion)
{
    var request = new AssignAuthorizationRequest
    {
        Version = currentVersion,
        PersonIdentityKey = "vecu_gfTRAjYnn_y-8zj-aBc4dEf5",  // Alice
        ActorIdentifier = "ops-user-42@client.example.com",
    };

    try
    {
        var response = await _client.AssignAuthorizationToDriverAsync(
            authorizationId, request);

        Console.WriteLine($"Status: {response.Status}");  // ASSIGNED
        Console.WriteLine($"Assigned driver: {response.AssignedDriverPik}");
        Console.WriteLine(
            $"Revoked credentials: {string.Join(", ", response.RevokedCredentialIds)}");
    }
    catch (DriverNotOnListException ex)
    {
        Console.WriteLine(
            $"Driver {ex.RequestedPersonIdentityKey} not on list; " +
            "call UpdateAuthorizationDriversAsync first.");
    }
    catch (AuthorizationAlreadyAssignedToDifferentDriverException)
    {
        Console.WriteLine("Already ASSIGNED to a different driver.");
    }
    catch (AssignPartialFailureException ex)
    {
        // Authorization IS assigned; credential-revoke partially failed.
        // Safe to retry with the bumped version.
        Console.WriteLine(
            $"Partial revocation: {ex.RevokedCredentialIds.Count} ok, " +
            $"{ex.FailedRevocations.Count} failed");
        var retryRequest = request with { Version = ex.CurrentVersion };
        await _client.AssignAuthorizationToDriverAsync(authorizationId, retryRequest);
    }
}

AddOrCreateDriverAsync()

SDK-side convenience wrapper (ADR-042 §Decision §10). Tries CreateAuthorizationAsync first; on 409 DUPLICATE_AUTHORIZATION for the same (VIN, origin), falls back to listing existing authorizations (auto-scoped to the caller's client_id) and UpdateAuthorizationDriversAsync to add the driver. Returns a unified result indicating which path was taken.

Returns: AddOrCreateDriverResult with:

• Authorization — the resulting authorization.
• Created — true if the POST path was taken; false if the PATCH fallback was taken.
• Added — true if UpdateAuthorizationDriversAsync actually added the driver; false if the driver was already on the existing list (idempotent no-op).

Exceptions: any exception raised by CreateAuthorizationAsync or UpdateAuthorizationDriversAsync. Only the specific 409 DUPLICATE_AUTHORIZATION case triggers the PATCH fallback — other 409 reasons (e.g., AUTHORIZATION_ALREADY_ASSIGNED) bubble up unchanged. ETag-mismatch retries are bounded; exhaustion raises RetryExhaustedException.

Example:

using CoxAuto.Vecu.CustodySdk.Models.Requests;
using CoxAuto.Vecu.CustodySdk.Models;
using CoxAuto.Vecu.CustodySdk.Exceptions;

public async Task AddOrCreate(string vin, string driverPik)
{
    var request = new AddOrCreateDriverRequest
    {
        Vin = vin,
        Origin = "1 Auction Blvd, Bordentown, NJ 08505",
        Destination = "200 Motor Ave, Columbus, OH 43230",
        Driver = new AuthorizedDriver
        {
            PersonIdentityKey = driverPik,
            Name = "Alice Driver",
        },
        AuthorizedBy = "dispatch-system",
        MakeModel = "Honda Accord 2023",
        ActorIdentifier = "ops-user-42@client.example.com",
    };

    try
    {
        var result = await _client.AddOrCreateDriverAsync(request);

        if (result.Created)
        {
            Console.WriteLine(
                $"Created new authorization {result.Authorization.AuthorizationId}");
        }
        else if (result.Added)
        {
            Console.WriteLine(
                $"Added driver to existing authorization {result.Authorization.AuthorizationId}");
        }
        else
        {
            Console.WriteLine("Driver was already on the list (no-op)");
        }
    }
    catch (RetryExhaustedException)
    {
        // ETag conflicts persisted past the retry budget — concurrent
        // modification by another caller
        Console.WriteLine("Concurrent modifications exhausted retry budget");
    }
}

Response Objects

AuthorizationResponse

Response after creating an authorization. Returned on 201 Created. On 409 Conflict, embedded as DuplicateAuthorizationException.ExistingAuthorization only when the disclosure guard passes (same client) AND service-side enrichment succeeded. Per ADR-042, the disclosure guard simplified to same_client only — cross-tenant collisions return the conflict but omit ExistingAuthorization and the Location header. The service still falls back to the minimal envelope on enrichment failure even when the guard would otherwise pass, so a null ExistingAuthorization does not by itself imply a cross-tenant conflict.

AuthorizationDetails

Detailed authorization information.

CancelAuthorizationResponse

Response after cancelling an authorization.

AuthorizedDriver (ADR-042)

Per-driver entry on a multi-driver authorization.

UpdateDriversResponse (ADR-042)

Returned by UpdateAuthorizationDriversAsync().

AssignAuthorizationResponse (ADR-042)

Returned by AssignAuthorizationToDriverAsync(). Extends the standard authorization shape with revocation telemetry from the sync-blocking AC-12 contract.

Common Use Cases

Auction to Dealership Transfer

public async Task<string> CreateAuctionTransfer(
    string vin,
    string driverIdentity)
{
    var request = new CreateAuthorizationRequest
    {
        Vin = vin,
        Origin = "1180 Lake Hearn Dr NE, Atlanta, GA 30342",
        Destination = "4101 Millenia Blvd, Orlando, FL 32839",
        PersonIdentityKey = driverIdentity,
        MakeModel = "Toyota Camry",
        TransportOrderId = $"TO-{DateTime.UtcNow:yyyyMMdd}-001",
        AuthorizedBy = "auction-integration-service",
        ValidUntil = DateTimeOffset.UtcNow.AddHours(72),  // 3 days
        Role = AuthorizationRole.DRIVER
    };

    var auth = await _client.CreateAuthorizationAsync(request);

    Console.WriteLine($"Authorization {auth.AuthorizationId} created");
    Console.WriteLine($"Expires at: {auth.ExpiresAt:yyyy-MM-dd HH:mm}");

    return auth.AuthorizationId;
}

Wait for Authorization Release

public async Task<AuthorizationDetails> CreateAndWaitForRelease(
    CreateAuthorizationRequest request)
{
    // Create authorization
    var auth = await _client.CreateAuthorizationAsync(request);

    Console.WriteLine($"Authorization {auth.AuthorizationId} created with status {auth.Status}");

    // Wait for authorization to be released
    var options = new WaitOptions
    {
        PollingIntervalSeconds = 5,
        TimeoutSeconds = 300,
        CustomPredicate = a => a.Status == AuthorizationStatus.RELEASED
    };

    var details = await _client.WaitForAuthorizationAsync(
        auth.AuthorizationId,
        options);

    Console.WriteLine($"Authorization {details.AuthorizationId} released");

    return details;
}

Monitor Authorization Status

public async Task MonitorAuthorization(string authorizationId)
{
    while (true)
    {
        var details = await _client.GetAuthorizationAsync(authorizationId);

        Console.WriteLine($"Status: {details.Status}");

        if (details.Status == AuthorizationStatus.RELEASED ||
            details.Status == AuthorizationStatus.CANCELLED ||
            details.Status == AuthorizationStatus.EXPIRED ||
            details.Status == AuthorizationStatus.REVOKED)
        {
            Console.WriteLine("Authorization reached terminal status");
            break;
        }

        await Task.Delay(TimeSpan.FromSeconds(10));
    }
}

Error Handling Pattern

using CoxAuto.Vecu.CustodySdk.Exceptions;

public async Task<AuthorizationResponse?> CreateAuthorizationWithRetry(
    CreateAuthorizationRequest request,
    int maxRetries = 3)
{
    for (int attempt = 1; attempt <= maxRetries; attempt++)
    {
        try
        {
            return await _client.CreateAuthorizationAsync(request);
        }
        catch (DuplicateAuthorizationException ex)
        {
            // Authorization already exists - not retryable
            Console.WriteLine($"Duplicate authorization: {ex.Message}");
            throw;
        }
        catch (VehicleNotReleasableException ex)
        {
            // Vehicle not releasable - not retryable
            Console.WriteLine($"Vehicle not releasable: {ex.Message}");
            throw;
        }
        catch (RateLimitException ex)
        {
            // Rate limited - wait and retry
            if (attempt < maxRetries)
            {
                var delay = ex.RetryAfter ?? TimeSpan.FromSeconds(30);
                Console.WriteLine($"Rate limited, retrying after {delay}");
                await Task.Delay(delay);
            }
        }
        catch (NetworkException ex)
        {
            // Network error - retry with backoff
            if (attempt < maxRetries)
            {
                var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt));
                Console.WriteLine($"Network error, retrying in {delay}");
                await Task.Delay(delay);
            }
        }
    }

    return null;
}

Multi-Driver Exception Hierarchy (ADR-042)

Multi-driver operations introduce additional typed exceptions. Most inherit from intermediate base classes — e.g., MultiDriverModeRequiredException is a subclass of InvalidConfigurationException, mirroring the existing InvalidOriginAddressException precedent.

// Catch the parent class to handle the whole config-error family at once
try
{
    await _client.UpdateAuthorizationDriversAsync(authorizationId, request);
}
catch (InvalidConfigurationException ex)
{
    // Handles MultiDriverModeRequiredException + any future config errors
    Console.WriteLine($"Configuration issue: {ex.Message}");
}

Next Steps

• Multi-Driver Integration Guide - End-to-end flows for multi_driver mode
• Multi-Driver Migration Guide - Moving from exception-mode to strict-only uniqueness
• Releasability API - Check vehicle releasability
• Error Handling - Exception types and handling
• Testing - Mock client for testing