Vehicle Custody

Developer Hub

Access and Authorization

Get marketplace access and configure authentication for all Vehicle Custody products.

Requesting Access

To use any Vehicle Custody product, you need access through the Cox Automotive Marketplace. Follow these steps:

Step 1: Create an Account

Register at the Cox Automotive Developer Portal

Step 2: Subscribe to Vehicle Custody

Navigate to the Marketplace and subscribe to the Vehicle Custody product.

Step 3: Approval Process

Your subscription request will be reviewed by the Cox Automotive team. Once approved, you will have access to the Vehicle Custody service.

Ready to Get Started?

Request Access on the Marketplace

Authentication Options

Vehicle Custody SDKs support two authentication patterns depending on your use case:

PatternUse CaseToken SourceRecommended
CIP Bearer TokenServer-side operations, Web SDKCIP OAuth2 endpointAll SDKs
User Token ExchangeMobile apps with user identityYour IdP + VECU AuthorizationMobile SDKs

Both patterns use the OAuth 2.0 endpoint internally. SDKs handle token exchange automatically — you only need to provide the initial token.

Obtaining the CIP Bearer Token

Once you have access to the Vehicle Custody product, use the CIP token endpoint to obtain a bearer token for SDK authentication. The token endpoint URL is provided in your marketplace subscription details for each environment.

Token Request

curl --location 'https://auth.manheim.com/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {base64_encoded_client_id:client_secret}' \
--header 'User-Agent: SomeValue' \
--data-urlencode 'scope=vehicle.custody.some.sdk' \
--data-urlencode 'grant_type=client_credentials'

Web SDK Authentication

The Web SDK uses CIP bearer tokens directly:

import { createVecuIDVSDK } from 'vec-idp-web-sdk';

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  bearerToken: 'your-cip-access-token-here',
});

React Native SDK Authentication

The React Native SDK handles token exchange internally using the OAuth 2.0 token exchange protocol (RFC 8693). Your app simply initializes the SDK with your user's Identity Provider (IdP) token, and the SDK takes care of the rest — including automatic refresh token rotation for long-lived sessions.

Setup Overview

  1. Register your IdP with VECU Configuration Service (one-time setup)
  2. Initialize the SDK with your user's IdP token

Step 1: Register Your Auth Configuration

Use the CIP bearer token to register your IdP's JWKS endpoint and issuer with the VECU Configuration Service. This is a one-time setup per environment.

VECU Configuration Service

This one-time registration is with the VECU Configuration Service and is required before the SDK can perform token exchange for mobile apps.

curl --request POST 'https://{vecu_config_url}/auth-config' \
--header 'Authorization: Bearer {cip_access_token}' \
--header 'Content-Type: application/json' \
--data '{
  "jwksUrl": "https://your-idp.com/.well-known/jwks.json",
  "expectedIssuer": "https://your-idp.com/",
  "uniqueIdKey": "sub"
}'
jwksUrlstringrequired

Your Identity Provider's JWKS endpoint URL for token validation.

expectedIssuerstringrequired

Expected iss claim in user tokens.

uniqueIdKeystringDefault: sub

The JWT claim key that contains a value unique to each end-user in your system. This is used to map your users to VECU identities for all custody and wallet transactions. Common values are sub (default), userId, or email. The value at this key must be consistent and stable for each user across sessions — it becomes the foundation for all VECU event correlation and transaction mapping.

Choosing uniqueIdKey

Choose a claim that uniquely and permanently identifies each user in your system. If you change this value after users have been provisioned, their VECU identity will change — creating new user records instead of matching existing ones. This affects custody assignments, wallet credentials, and event history.

Issuer Uniqueness

The expectedIssuer must be globally unique across all VECU clients. This value is used to identify which client a user token belongs to during token exchange. This token issuer can be shared when one organization services the same group of end-users through multiple CIP clients.

Step 2: Initialize the SDK

Pass your user's IdP token directly to the SDK. The SDK handles all token exchange and refresh token rotation internally via theOAuth 2.0 endpoint.

import { VECUProvider } from '@vecu/wallet-react-native-sdk';

const [authToken, setAuthToken] = useState<string | null>(null);

useEffect(() => {
  async function initAuth() {
    // Get the user's token from your Identity Provider
    const token = await yourAuthService.getUserToken();
    setAuthToken(token);
  }
  initAuth();
}, []);

if (!authToken) {
  return <LoadingScreen />;
}

return (
  <VECUProvider
    config={{
      deploymentStage: 'sandbox',
      authToken, // Your user's IdP token - SDK handles exchange internally
      useTokenExchange: true,
      onTokenExpired: async () => {
        // Refresh the user's IdP token and update state
        const newToken = await yourAuthService.refreshUserToken();
        setAuthToken(newToken);
      },
    }}
  >
    <App />
  </VECUProvider>
);

Security Best Practices

  1. Never expose CIP credentials in client-side code - CIP token exchange should happen on your server
  2. User tokens are safe for mobile - The SDK's internal token exchange is designed for client-side use
  3. Store tokens securely - Use environment variables or secure storage
  4. Implement token refresh - Handle token expiration gracefully
  5. Use HTTPS only - All connections should use HTTPS
  6. Rotate credentials regularly - Update your client secret periodically
  7. Use tokens with official SDKs only — Do not use bearer tokens to call internal API endpoints directly. The SDKs handle all API communication on your behalf.

Next Steps